truelight@9579: /* $Id$ */
truelight@9579: 
truebrain@9829: /** @file ai_abstractlist.hpp A list which can keep item/value pairs, which you can walk. */
truebrain@9829: /** @defgroup AIList Classes that create a list of items. */
truelight@9579: 
truelight@9593: #ifndef AI_ABSTRACTLIST_HPP
truelight@9593: #define AI_ABSTRACTLIST_HPP
truelight@9579: 
truelight@9579: #include "ai_object.hpp"
truelight@9579: #include <map>
truelight@9579: #include <set>
truelight@9579: 
truelight@9593: class AIAbstractListSorter;
truelight@9579: 
truelight@9579: /**
truebrain@9829:  * Class that creates a list which can keep item/value pairs, which you can walk.
truelight@9579:  */
truelight@9593: class AIAbstractList : public AIObject {
rubidium@9665: public:
truebrain@9829: 	static const char *GetClassName() { return "AIAbstractList"; }
truebrain@9829: 
rubidium@9665: 	/** Type of sorter */
rubidium@9665: 	enum SorterType {
truelight@9681: 		SORT_BY_VALUE,
truelight@9681: 		SORT_BY_ITEM,
rubidium@9665: 	};
rubidium@9665: 
truelight@9579: private:
truelight@9593: 	AIAbstractListSorter *sorter;
rubidium@9665: 	SorterType sorter_type;
rubidium@9665: 	bool sort_ascending;
truebrain@9752: 	bool initialized;
truelight@9579: 
truelight@9579: public:
rubidium@9853: 	typedef std::set<int32> AIItemList;                       //!< The list of items inside the bucket
rubidium@9853: 	typedef std::map<int32, AIItemList> AIAbstractListBucket; //!< The bucket list per value
rubidium@9853: 	typedef std::map<int32, int32> AIAbstractListMap;         //!< List per item
truelight@9579: 
rubidium@9853: 	AIAbstractListMap items;           //!< The items in the list
rubidium@9853: 	AIAbstractListBucket buckets;      //!< The items in the list, sorted by value
truelight@9579: 
truelight@9593: protected:
truelight@9579: 	/**
truelight@9579: 	 * Add a single item to the list.
truelight@9579: 	 * @param item the item to add. Should be unique, otherwise it is ignored.
truelight@9579: 	 * @note the value is set to 0 by default.
truelight@9579: 	 */
truelight@9579: 	void AddItem(int32 item);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Remove a single item from the list.
truelight@9579: 	 * @param item the item to remove. If not existing, it is ignored.
truelight@9579: 	 */
truelight@9579: 	void RemoveItem(int32 item);
truelight@9579: 
truelight@9593: public:
truelight@9593: 	AIAbstractList();
truelight@9593: 	~AIAbstractList();
truelight@9593: 
truelight@9593: 	/**
truelight@9593: 	 * Clear the list, making Count() returning 0 and IsEmpty() returning true.
truelight@9593: 	 */
truelight@9593: 	void Clear();
truelight@9593: 
truelight@9579: 	/**
truelight@9579: 	 * Check if an item is in the list.
truelight@9579: 	 * @param item the item to check for.
truelight@9579: 	 * @return true if the item is in the list.
truelight@9579: 	 */
truelight@9579: 	bool HasItem(int32 item);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Go to the beginning of the list.
truelight@9579: 	 * @return the item value of the first item.
truelight@9579: 	 */
truelight@9579: 	int32 Begin();
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Go to the next item in the list.
truelight@9579: 	 * @return the item value of the next item.
truelight@9579: 	 * @note returns 0 if beyond end-of-list. Use HasNext() to check for end-of-list.
truelight@9579: 	 */
truelight@9579: 	int32 Next();
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Check if a list is empty.
truelight@9579: 	 * @return true if the list is empty.
rubidium@9843: 	 */
truelight@9579: 	bool IsEmpty();
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Check if there is a next element. In other words, if this is true,
truelight@9579: 	 *   Next() will return a valid item.
truelight@9579: 	 * @return true if there is a next item.
truelight@9579: 	 */
truelight@9579: 	bool HasNext();
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Returns the amount of items in the list.
truelight@9579: 	 * @return amount of items in the list.
truelight@9579: 	 */
truelight@9579: 	int32 Count();
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Get the value that belongs to this item.
truelight@9579: 	 * @param item the item to get the value from
truelight@9579: 	 * @return the value that belongs to this item.
truelight@9579: 	 */
truelight@9579: 	int32 GetValue(int32 item);
truelight@9579: 
truelight@9579: 	/**
truelight@9664: 	 * Set a value of an item directly.
truelight@9664: 	 * @param item the item to set the value for.
truelight@9664: 	 * @param value the value to give to the item
truelight@9664: 	 * @return true if we could set the item to value, false otherwise.
truelight@9664: 	 */
truelight@9664: 	bool SetValue(int32 item, int32 value);
truelight@9664: 
truelight@9664: 	/**
rubidium@9665: 	 * Sort this list by the given sorter and direction.
rubidium@9665: 	 * @param sorter    the type of sorter to use
truelight@9579: 	 * @param ascending if true, lowest value is on top, else at bottom.
truelight@9579: 	 * @note the current item stays at the same place.
truelight@9579: 	 */
rubidium@9665: 	void Sort(SorterType sorter, bool ascending);
truelight@9579: 
truelight@9579: 	/**
truebrain@9796: 	 * Add one list to an other one.
truebrain@9796: 	 * @param list The list that will be added to the caller.
truebrain@9796: 	 * @post The list to be added ('list') stays unmodified.
truebrain@9796: 	 * @note All added items keep their value as it was in 'list'.
truebrain@9796: 	 * @note If the item already exists inside the caller, the value of the
truebrain@9796: 	 *  list that is added is set on the item.
truebrain@9796: 	 */
truebrain@9796: 	void AddList(AIAbstractList *list);
truebrain@9796: 
truebrain@9796: 	/**
truelight@9579: 	 * Removes all items with a higher value than 'value'.
truelight@9579: 	 * @param value the value above which all items are removed.
truelight@9579: 	 */
truelight@9579: 	void RemoveAboveValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Removes all items with a lower value than 'value'.
truelight@9579: 	 * @param value the value below which all items are removed.
truelight@9579: 	 */
truelight@9579: 	void RemoveBelowValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Removes all items with a value above start and below end.
truelight@9579: 	 * @param start the lower bound of the to be removed values (exclusive).
truelight@9579: 	 * @param end   the upper bound of the to be removed valuens (exclusive).
truelight@9579: 	 */
truelight@9579: 	void RemoveBetweenValue(int32 start, int32 end);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Remove all items with this value.
truelight@9579: 	 * @param value the value to remove.
truelight@9579: 	 */
truelight@9579: 	void RemoveValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
rubidium@9665: 	 * Remove the first count items.
rubidium@9665: 	 * @param count the amount of items to remove.
rubidium@9665: 	 */
rubidium@9665: 	void RemoveTop(int32 count);
rubidium@9665: 
rubidium@9665: 	/**
rubidium@9665: 	 * Remove the last count items.
rubidium@9665: 	 * @param count the amount of items to remove.
rubidium@9665: 	 */
rubidium@9665: 	void RemoveBottom(int32 count);
rubidium@9665: 
rubidium@9665: 	/**
rubidium@9665: 	 * Remove everything that is in the given list from this list (same item index that is).
rubidium@9665: 	 * @param list the list of items to remove.
rubidium@9665: 	 * @pre list != NULL
rubidium@9665: 	 */
rubidium@9665: 	void RemoveList(AIAbstractList *list);
rubidium@9665: 
rubidium@9665: 	/**
truelight@9579: 	 * Keep all items with a higher value than 'value'.
truelight@9579: 	 * @param value the value above which all items are kept.
truelight@9579: 	 */
truelight@9579: 	void KeepAboveValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Keep all items with a lower value than 'value'.
truelight@9579: 	 * @param value the value below which all items are kept.
truelight@9579: 	 */
truelight@9579: 	void KeepBelowValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Keep all items with a value above start and below end.
truelight@9579: 	 * @param start the lower bound of the to be kept values (exclusive).
truelight@9579: 	 * @param end   the upper bound of the to be kept values (exclusive).
truelight@9579: 	 */
truelight@9579: 	void KeepBetweenValue(int32 start, int32 end);
truelight@9579: 
truelight@9579: 	/**
truelight@9579: 	 * Keep all items with this value.
truelight@9579: 	 * @param value the value to keep.
truelight@9579: 	 **/
truelight@9579: 	void KeepValue(int32 value);
truelight@9579: 
truelight@9579: 	/**
rubidium@9665: 	 * Keep the first count items, i.e. remove everything except the first count items.
rubidium@9665: 	 * @param count the amount of items to keep.
rubidium@9665: 	 */
rubidium@9665: 	void KeepTop(int32 count);
rubidium@9665: 
rubidium@9665: 	/**
rubidium@9665: 	 * Keep the last count items, i.e. remove everything except the last count items.
rubidium@9665: 	 * @param count the amount of items to keep.
rubidium@9665: 	 */
rubidium@9665: 	void KeepBottom(int32 count);
rubidium@9665: 
rubidium@9665: 	/**
rubidium@9665: 	 * Keps everything that is in the given list from this list (same item index that is).
rubidium@9665: 	 * @param list the list of items to keep.
rubidium@9665: 	 * @pre list != NULL
rubidium@9665: 	 */
rubidium@9665: 	void KeepList(AIAbstractList *list);
rubidium@9665: 
rubidium@9665: 	/**
truelight@9579: 	 * Give all items a value defined by the valuator you give.
truebrain@9814: 	 * @param vm Internal pointer, not something you need to specify.
rubidium@9843: 	 * @return The result of the valuation.
truebrain@9814: 	 * @note The first param for this function is the function you want to use
truebrain@9814: 	 *  to valuate the items in the list. It should accept at least one integer
truebrain@9814: 	 *  which will be set to the item, and should return an integer, which will
truebrain@9814: 	 *  become the value of the item. Additional parameters are possible, then
truebrain@9814: 	 *  you need to add them to the Valuator to. Example:
truebrain@9814: 	 *  list.Valuate(AIBridge.GetPrice, 5);
truebrain@9814: 	 *  list.Valuate(AIBridge.GetMaxLength);
truebrain@9814: 	 *  function MyVal(bridge_id, myparam) {
truebrain@9814: 	 *    return myparam * bridge_id; // This is silly
truebrain@9814: 	 *  }
truebrain@9814: 	 *  list.Valuate(MyVal, 12);
truelight@9579: 	 */
truebrain@9814: 	SQInteger Valuate(HSQUIRRELVM vm);
truelight@9579: };
truelight@9579: 
truelight@9579: #endif /* AI_LIST_HPP */