src/script/api/script_list.hpp

   1 /* $Id: script_list.hpp 25579 2013-07-10 15:38:42Z rubidium $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD 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.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file script_list.hpp A list which can keep item/value pairs, which you can walk. */
  11 /** @defgroup ScriptList Classes that create a list of items. */
  12
  13 #ifndef SCRIPT_LIST_HPP
  14 #define SCRIPT_LIST_HPP
  15
  16 #include "script_object.hpp"
  17 #include <map>
  18 #include <set>
  19
  20 class ScriptListSorter;
  21
  22 /**
  23  * Class that creates a list which can keep item/value pairs, which you can walk.
  24  * @api ai game
  25  */
  26 class ScriptList : public ScriptObject {
  27 public:
  28         /** Type of sorter */
  29         enum SorterType {
  30                 SORT_BY_VALUE, ///< Sort the list based on the value of the item.
  31                 SORT_BY_ITEM,  ///< Sort the list based on the item itself.
  32         };
  33
  34         /** Sort ascending */
  35         static const bool SORT_ASCENDING = true;
  36         /** Sort descending */
  37         static const bool SORT_DESCENDING = false;
  38
  39 private:
  40         ScriptListSorter *sorter;     ///< Sorting algorithm
  41         SorterType sorter_type;       ///< Sorting type
  42         bool sort_ascending;          ///< Whether to sort ascending or descending
  43         bool initialized;             ///< Whether an iteration has been started
  44         int modifications;            ///< Number of modification that has been done. To prevent changing data while valuating.
  45
  46 public:
  47         typedef std::set<int64> ScriptItemList;                   ///< The list of items inside the bucket
  48         typedef std::map<int64, ScriptItemList> ScriptListBucket; ///< The bucket list per value
  49         typedef std::map<int64, int64> ScriptListMap;             ///< List per item
  50
  51         ScriptListMap items;           ///< The items in the list
  52         ScriptListBucket buckets;      ///< The items in the list, sorted by value
  53
  54         ScriptList();
  55         ~ScriptList();
  56
  57 #ifdef DOXYGEN_API
  58         /**
  59          * Add a single item to the list.
  60          * @param item the item to add. Should be unique, otherwise it is ignored.
  61          * @param value the value to assign.
  62          */
  63         void AddItem(int64 item, int64 value);
  64 #else
  65         void AddItem(int64 item, int64 value = 0);
  66 #endif /* DOXYGEN_API */
  67
  68         /**
  69          * Remove a single item from the list.
  70          * @param item the item to remove. If not existing, it is ignored.
  71          */
  72         void RemoveItem(int64 item);
  73
  74         /**
  75          * Clear the list, making Count() returning 0 and IsEmpty() returning true.
  76          */
  77         void Clear();
  78
  79         /**
  80          * Check if an item is in the list.
  81          * @param item the item to check for.
  82          * @return true if the item is in the list.
  83          */
  84         bool HasItem(int64 item);
  85
  86         /**
  87          * Go to the beginning of the list and return the item. To get the value use list.GetValue(list.Begin()).
  88          * @return the first item.
  89          * @note returns 0 if beyond end-of-list. Use IsEnd() to check for end-of-list.
  90          */
  91         int64 Begin();
  92
  93         /**
  94          * Go to the next item in the list and return the item. To get the value use list.GetValue(list.Next()).
  95          * @return the next item.
  96          * @note returns 0 if beyond end-of-list. Use IsEnd() to check for end-of-list.
  97          */
  98         int64 Next();
  99
 100         /**
 101          * Check if a list is empty.
 102          * @return true if the list is empty.
 103          */
 104         bool IsEmpty();
 105
 106         /**
 107          * Check if there is a element left. In other words, if this is false,
 108          * the last call to Begin() or Next() returned a valid item.
 109          * @return true if the current item is beyond end-of-list.
 110          */
 111         bool IsEnd();
 112
 113         /**
 114          * Returns the amount of items in the list.
 115          * @return amount of items in the list.
 116          */
 117         int32 Count();
 118
 119         /**
 120          * Get the value that belongs to this item.
 121          * @param item the item to get the value from
 122          * @return the value that belongs to this item.
 123          */
 124         int64 GetValue(int64 item);
 125
 126         /**
 127          * Set a value of an item directly.
 128          * @param item the item to set the value for.
 129          * @param value the value to give to the item
 130          * @return true if we could set the item to value, false otherwise.
 131          * @note Changing values of items while looping through a list might cause
 132          *  entries to be skipped. Be very careful with such operations.
 133          */
 134         bool SetValue(int64 item, int64 value);
 135
 136         /**
 137          * Sort this list by the given sorter and direction.
 138          * @param sorter    the type of sorter to use
 139          * @param ascending if true, lowest value is on top, else at bottom.
 140          * @note the current item stays at the same place.
 141          * @see SORT_ASCENDING SORT_DESCENDING
 142          */
 143         void Sort(SorterType sorter, bool ascending);
 144
 145         /**
 146          * Add one list to another one.
 147          * @param list The list that will be added to the caller.
 148          * @post The list to be added ('list') stays unmodified.
 149          * @note All added items keep their value as it was in 'list'.
 150          * @note If the item already exists inside the caller, the value of the
 151          *  list that is added is set on the item.
 152          */
 153         void AddList(ScriptList *list);
 154
 155         /**
 156          * Swap the contents of two lists.
 157          * @param list The list that will be swapped with.
 158          */
 159         void SwapList(ScriptList *list);
 160
 161         /**
 162          * Removes all items with a higher value than 'value'.
 163          * @param value the value above which all items are removed.
 164          */
 165         void RemoveAboveValue(int64 value);
 166
 167         /**
 168          * Removes all items with a lower value than 'value'.
 169          * @param value the value below which all items are removed.
 170          */
 171         void RemoveBelowValue(int64 value);
 172
 173         /**
 174          * Removes all items with a value above start and below end.
 175          * @param start the lower bound of the to be removed values (exclusive).
 176          * @param end   the upper bound of the to be removed values (exclusive).
 177          */
 178         void RemoveBetweenValue(int64 start, int64 end);
 179
 180         /**
 181          * Remove all items with this value.
 182          * @param value the value to remove.
 183          */
 184         void RemoveValue(int64 value);
 185
 186         /**
 187          * Remove the first count items.
 188          * @param count the amount of items to remove.
 189          */
 190         void RemoveTop(int32 count);
 191
 192         /**
 193          * Remove the last count items.
 194          * @param count the amount of items to remove.
 195          */
 196         void RemoveBottom(int32 count);
 197
 198         /**
 199          * Remove everything that is in the given list from this list (same item index that is).
 200          * @param list the list of items to remove.
 201          * @pre list != NULL
 202          */
 203         void RemoveList(ScriptList *list);
 204
 205         /**
 206          * Keep all items with a higher value than 'value'.
 207          * @param value the value above which all items are kept.
 208          */
 209         void KeepAboveValue(int64 value);
 210
 211         /**
 212          * Keep all items with a lower value than 'value'.
 213          * @param value the value below which all items are kept.
 214          */
 215         void KeepBelowValue(int64 value);
 216
 217         /**
 218          * Keep all items with a value above start and below end.
 219          * @param start the lower bound of the to be kept values (exclusive).
 220          * @param end   the upper bound of the to be kept values (exclusive).
 221          */
 222         void KeepBetweenValue(int64 start, int64 end);
 223
 224         /**
 225          * Keep all items with this value.
 226          * @param value the value to keep.
 227          */
 228         void KeepValue(int64 value);
 229
 230         /**
 231          * Keep the first count items, i.e. remove everything except the first count items.
 232          * @param count the amount of items to keep.
 233          */
 234         void KeepTop(int32 count);
 235
 236         /**
 237          * Keep the last count items, i.e. remove everything except the last count items.
 238          * @param count the amount of items to keep.
 239          */
 240         void KeepBottom(int32 count);
 241
 242         /**
 243          * Keeps everything that is in the given list from this list (same item index that is).
 244          * @param list the list of items to keep.
 245          * @pre list != NULL
 246          */
 247         void KeepList(ScriptList *list);
 248
 249 #ifndef DOXYGEN_API
 250         /**
 251          * Used for 'foreach()' and [] get from Squirrel.
 252          */
 253         SQInteger _get(HSQUIRRELVM vm);
 254
 255         /**
 256          * Used for [] set from Squirrel.
 257          */
 258         SQInteger _set(HSQUIRRELVM vm);
 259
 260         /**
 261          * Used for 'foreach()' from Squirrel.
 262          */
 263         SQInteger _nexti(HSQUIRRELVM vm);
 264
 265         /**
 266          * The Valuate() wrapper from Squirrel.
 267          */
 268         SQInteger Valuate(HSQUIRRELVM vm);
 269 #else
 270         /**
 271          * Give all items a value defined by the valuator you give.
 272          * @param valuator_function The function which will be doing the valuation.
 273          * @param params The params to give to the valuators (minus the first param,
 274          *  which is always the index-value we are valuating).
 275          * @note You may not add, remove or change (setting the value of) items while
 276          *  valuating. You may also not (re)sort while valuating.
 277          * @note You can write your own valuators and use them. Just remember that
 278          *  the first parameter should be the index-value, and it should return
 279          *  an integer.
 280          * @note Example:
 281          *  list.Valuate(ScriptBridge.GetPrice, 5);
 282          *  list.Valuate(ScriptBridge.GetMaxLength);
 283          *  function MyVal(bridge_id, myparam)
 284          *  {
 285          *    return myparam * bridge_id; // This is silly
 286          *  }
 287          *  list.Valuate(MyVal, 12);
 288          */
 289         void Valuate(void *valuator_function, int params, ...);
 290 #endif /* DOXYGEN_API */
 291 };
 292
 293 #endif /* SCRIPT_LIST_HPP */