Priority.h

00001 /***************************************************************************
00002  *                                                                         *
00003  *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
00004  *       mailto: <tevs@mpi-sb.mpg.de>                                      *
00005  *                                                                         *
00006  *   This program is free software; you can redistribute it and/or modify  *
00007  *   it under the terms of the GNU General Public License as published by  *
00008  *   the Free Software Foundation; either version 2 of the License, or     *
00009  *   (at your option) any later version.                                   *
00010  *                                                                         *
00011  ***************************************************************************/
00012 
00013 
00014 #ifndef _NR_C_PRIORITY__H_
00015 #define _NR_C_PRIORITY__H_
00016 
00017         
00018 //----------------------------------------------------------------------------------
00019 // Includes
00020 //----------------------------------------------------------------------------------
00021 #include "Prerequisities.h"
00022 
00023 
00024 namespace nrEngine{
00025         
00026                 
00027         //! Priorities class definition
00028         /**
00029         * Priorities definition.
00030         * Priorities are used very often to determine for example which object should be removed
00031         * first or which one has to get access to some resources.
00032         *
00033         * In our engine we understand under priority numbers some numbers that handles like
00034         * integers. You have two operations defined on the priorities: addidition and substraction.
00035         * You can add integers to priority numbers to increase or decrease the meaning of such a priority.
00036         *
00037         * The class which use such priorities should know how to handle with them. That means it
00038         * has to know if the priority numbers are in increasing or decreasing order. Increasing order
00039         * means that the element with the lowest priority is coming at last and with the highest as first.
00040         * So to say colloquially, lower priority is better than higher. There can also be another
00041         * way: decreasing order. Which is converse to increasing order.
00042         *
00043         * All default priority numbers are stored in decreasing order. That means the best priority is
00044         * the priority with the smallest number. So you are welcome to use this definition or just
00045         * write you classes according to increasing definition.
00046         *
00047         * You can also create priority numbers from strings. The given string will first be scanned
00048         * for known names like "PRIORITY_FIRST" or "NR_PRIORITY_FIRST" and so on. If such known string
00049         * was found, so the value according to such a string will be assigned. If no such name found,
00050         * so standard boost's lexical cast will be used to cast for the value. So this can also fail
00051         * if the given string could not been casted. (e.g. "5bla" -> not castable)
00052         * \ingroup gp
00053         **/
00054         class _NRExport CPriority{
00055         public:
00056         
00057                 /**
00058                 * Couple of pririoty default definitions. Can be used to specify a priority of
00059                 * any elements with CPriority-Class
00060                 **/
00061                 typedef enum _PriorityType{
00062 
00063                         //! This number represents an immediate priority (better than first)
00064                         IMMEDIATE               = 0,
00065                         
00066                         //! Smallest possible priority number
00067                         FIRST                   = 1,
00068                         
00069                         //! Ultry high priority
00070                         ULTRA_HIGH              = 10000,
00071                         
00072                         //! Next smaller priority to the ultra high value
00073                         VERY_HIGH               = 20000,
00074                         
00075                         //! High priority
00076                         HIGH                    = 30000,
00077                         
00078                         //! Default priority for all definitions (Center point)
00079                         NORMAL                  = 40000,
00080                         
00081                         //! Lower priority according to the normal
00082                         LOW                             = 50000,
00083                         
00084                         //! Very low priority in relation to normal value
00085                         VERY_LOW                = 60000,
00086                         
00087                         //! Ultra low priority by comparison to the normal value
00088                         ULTRA_LOW               = 70000,
00089                         
00090                         //! Greatest possible priority number
00091                         LAST                    = 0x8FFFFFFE
00092                         
00093                 }PriorityType;
00094                         
00095                 //! Normal constructor
00096                 CPriority():    mPriority(NORMAL){}
00097                 
00098                 //! non-virtual destructor to prevent deriving of classes
00099                 ~CPriority()                            {}
00100                 
00101                 //! Copy constructor for priorities
00102                 CPriority(const CPriority& p){
00103                         mPriority = p.get();    
00104                 }
00105                 
00106                 //! Create priority object from a number
00107                 CPriority(const int32& n): mPriority(n) {}
00108                         
00109                 /**
00110                 * Create the priority from a string. String can contain either a number or
00111                 * a character array with priority names e.g. "PRIORITY_LAST"
00112                 **/
00113                 CPriority(const std::string& str){
00114                         
00115                         if (str.length() == 0){ mPriority = NORMAL;}
00116                         #define _PRIORITY_(name)        else if (str == #name){ mPriority = name;}
00117                         _PRIORITY_(FIRST)
00118                         _PRIORITY_(ULTRA_HIGH)
00119                         _PRIORITY_(VERY_HIGH)
00120                         _PRIORITY_(HIGH)
00121                         _PRIORITY_(NORMAL)
00122                         _PRIORITY_(LOW)
00123                         _PRIORITY_(VERY_LOW)
00124                         _PRIORITY_(ULTRA_LOW)
00125                         _PRIORITY_(LAST)
00126                         #undef _PRIORITY_
00127                         else{
00128                                 mPriority = boost::lexical_cast<uint32>(str);
00129                         }
00130                 }
00131                 
00132                 //! Get the priority as an integer number, Number will be saturated
00133                 operator        int32() const { return u2i(mPriority);}
00134                 
00135                 //! Get the priority number
00136                 operator        uint32() const { return mPriority;}
00137                 
00138                 //! add new value to the priority number
00139                 CPriority&      operator        += (const CPriority& p) {mPriority += p.get(); return *this;}
00140                 CPriority&      operator        += (const uint32& p)            {mPriority += p; return *this;}
00141                 
00142                 //! Add an integer value can produce negative values
00143                 CPriority&      operator        += (const int32& p)                     {mPriority = i2u(u2i(mPriority) + p); return *this;}
00144                 
00145                 //! Substract a value from the priority by appropriate conversion between these types
00146                 CPriority&      operator        -= (const CPriority& p) {mPriority = i2u(u2i(mPriority) - u2i(p.get())); return *this;}
00147                 CPriority&      operator        -= (const int32& p)                     {mPriority = i2u(u2i(mPriority) - p); return *this;}
00148                 CPriority&      operator        -= (const uint32& p)            {mPriority = i2u(u2i(mPriority) - u2i(p)); return *this;}
00149         
00150                 //! Check the priority eqiuvalence and order to other values
00151                 bool    operator        < (const CPriority& p)  const{return mPriority < p.get();}
00152                 bool    operator        > (const CPriority& p)  const{return mPriority > p.get();}
00153                 bool    operator        ==(const CPriority& p)  const{return mPriority == p.get();}
00154                 bool    operator        !=(const CPriority& p)  const{return mPriority != p.get();}
00155                 bool    operator        <=(const CPriority& p)  const{return mPriority <= p.get();}
00156                 bool    operator        >=(const CPriority& p)  const{return mPriority >= p.get();}
00157         
00158                 //! Check the priority eqiuvalence and order to other integer values
00159                 bool    operator        < (const int32& p)      const{return mPriority < i2u(p);}
00160                 bool    operator        > (const int32& p)      const{return mPriority > i2u(p);}
00161                 bool    operator        ==(const int32& p)      const{return mPriority == i2u(p);}
00162                 bool    operator        !=(const int32& p)      const{return mPriority != i2u(p);}
00163                 bool    operator        <=(const int32& p)      const{return mPriority <= i2u(p);}
00164                 bool    operator        >=(const int32& p)      const{return mPriority >= i2u(p);}
00165 
00166                 //! Check to PriorityType
00167                 bool    operator        < (PriorityType p)      const{return mPriority < (uint32)p;}
00168                 bool    operator        > (PriorityType p)      const{return mPriority > (uint32)p;}
00169                 bool    operator        ==(PriorityType p)      const{return mPriority == (uint32)p;}
00170                 bool    operator        !=(PriorityType p)      const{return mPriority != (uint32)p;}
00171                 bool    operator        <=(PriorityType p)      const{return mPriority <= (uint32)p;}
00172                 bool    operator        >=(PriorityType p)      const{return mPriority >= (uint32)p;}
00173                 
00174                 //! Convert to a string
00175                 operator std::string(){
00176                         if (false){}
00177                         #define _PRIORITY_(name)        else if (mPriority == name){ return std::string(#name);}
00178                         _PRIORITY_(IMMEDIATE)
00179                         _PRIORITY_(FIRST)
00180                         _PRIORITY_(ULTRA_HIGH)
00181                         _PRIORITY_(VERY_HIGH)
00182                         _PRIORITY_(HIGH)
00183                         _PRIORITY_(NORMAL)
00184                         _PRIORITY_(LOW)
00185                         _PRIORITY_(VERY_LOW)
00186                         _PRIORITY_(ULTRA_LOW)
00187                         _PRIORITY_(LAST)
00188                         #undef _PRIORITY_
00189                         else{
00190                                 return boost::lexical_cast<std::string>(mPriority);
00191                         }
00192                 }
00193                 
00194                 private:
00195                         //! priority number
00196                         uint32  mPriority;
00197                 
00198                         //! Get the priority number
00199                         const uint32& get()const        {return mPriority;}
00200                 
00201                         //! Saturate an integer value to unsigned integer
00202                         uint32  i2u(const int32& i) const{
00203                                 if (i >= 0) return static_cast<uint32>(i);
00204                                 else            return 0;
00205                         }
00206                 
00207                         //! Saturate an unsigned integer signed integer
00208                         int32   u2i(const uint32& i) const {
00209                                 if (i < 0x8FFFFFFF) return static_cast<uint32>(i);
00210                                 else                            return 0x8FFFFFFE;
00211                         }
00212 
00213         };
00214         
00215         //! Write the priority without C prefix, to define it like normal type. \ingroup gp
00216         typedef         CPriority               Priority;
00217         
00218 }; // end namespace
00219 
00220 #endif
00221  

Generated on Wed Sep 12 23:19:42 2007 for nrEngine by  doxygen 1.5.1