(svn r27950) -Merge: Documentation updates from 1.7 branch
[openttd.git] / src / cargopacket.h
blob0ed4fd9bbca204327f9b880738e7a86623c99d56
1 /* $Id$ */
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 */
10 /** @file cargopacket.h Base class for cargo packets. */
12 #ifndef CARGOPACKET_H
13 #define CARGOPACKET_H
15 #include "core/pool_type.hpp"
16 #include "economy_type.h"
17 #include "station_type.h"
18 #include "order_type.h"
19 #include "cargo_type.h"
20 #include "vehicle_type.h"
21 #include "core/multimap.hpp"
22 #include <list>
24 /** Unique identifier for a single cargo packet. */
25 typedef uint32 CargoPacketID;
26 struct CargoPacket;
28 /** Type of the pool for cargo packets for a little over 16 million packets. */
29 typedef Pool<CargoPacket, CargoPacketID, 1024, 0xFFF000, PT_NORMAL, true, false> CargoPacketPool;
30 /** The actual pool with cargo packets. */
31 extern CargoPacketPool _cargopacket_pool;
33 struct GoodsEntry; // forward-declare for Stage() and RerouteStalePackets()
35 template <class Tinst, class Tcont> class CargoList;
36 class StationCargoList; // forward-declare, so we can use it in VehicleCargoList.
37 extern const struct SaveLoad *GetCargoPacketDesc();
39 typedef uint32 TileOrStationID;
41 /**
42 * Container for cargo from the same location and time.
44 struct CargoPacket : CargoPacketPool::PoolItem<&_cargopacket_pool> {
45 private:
46 Money feeder_share; ///< Value of feeder pickup to be paid for on delivery of cargo.
47 uint16 count; ///< The amount of cargo in this packet.
48 byte days_in_transit; ///< Amount of days this packet has been in transit.
49 SourceTypeByte source_type; ///< Type of \c source_id.
50 SourceID source_id; ///< Index of source, INVALID_SOURCE if unknown/invalid.
51 StationID source; ///< The station where the cargo came from first.
52 TileIndex source_xy; ///< The origin of the cargo (first station in feeder chain).
53 union {
54 TileOrStationID loaded_at_xy; ///< Location where this cargo has been loaded into the vehicle.
55 TileOrStationID next_station; ///< Station where the cargo wants to go next.
58 /** The CargoList caches, thus needs to know about it. */
59 template <class Tinst, class Tcont> friend class CargoList;
60 friend class VehicleCargoList;
61 friend class StationCargoList;
62 /** We want this to be saved, right? */
63 friend const struct SaveLoad *GetCargoPacketDesc();
64 public:
65 /** Maximum number of items in a single cargo packet. */
66 static const uint16 MAX_COUNT = UINT16_MAX;
68 CargoPacket();
69 CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id);
70 CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share = 0, SourceType source_type = ST_INDUSTRY, SourceID source_id = INVALID_SOURCE);
72 /** Destroy the packet. */
73 ~CargoPacket() { }
75 CargoPacket *Split(uint new_size);
76 void Merge(CargoPacket *cp);
77 void Reduce(uint count);
79 /**
80 * Sets the tile where the packet was loaded last.
81 * @param load_place Tile where the packet was loaded last.
83 void SetLoadPlace(TileIndex load_place) { this->loaded_at_xy = load_place; }
85 /**
86 * Sets the station where the packet is supposed to go next.
87 * @param next_station Next station the packet should go to.
89 void SetNextStation(StationID next_station) { this->next_station = next_station; }
91 /**
92 * Adds some feeder share to the packet.
93 * @param new_share Feeder share to be added.
95 void AddFeederShare(Money new_share) { this->feeder_share += new_share; }
97 /**
98 * Gets the number of 'items' in this packet.
99 * @return Item count.
101 inline uint16 Count() const
103 return this->count;
107 * Gets the amount of money already paid to earlier vehicles in
108 * the feeder chain.
109 * @return Feeder share.
111 inline Money FeederShare() const
113 return this->feeder_share;
117 * Gets part of the amount of money already paid to earlier vehicles in
118 * the feeder chain.
119 * @param part Amount of cargo to get the share for.
120 * @return Feeder share for the given amount of cargo.
122 inline Money FeederShare(uint part) const
124 return this->feeder_share * part / static_cast<uint>(this->count);
128 * Gets the number of days this cargo has been in transit.
129 * This number isn't really in days, but in 2.5 days (CARGO_AGING_TICKS = 185 ticks) and
130 * it is capped at 255.
131 * @return Length this cargo has been in transit.
133 inline byte DaysInTransit() const
135 return this->days_in_transit;
139 * Gets the type of the cargo's source. industry, town or head quarter.
140 * @return Source type.
142 inline SourceType SourceSubsidyType() const
144 return this->source_type;
148 * Gets the ID of the cargo's source. An IndustryID, TownID or CompanyID.
149 * @return Source ID.
151 inline SourceID SourceSubsidyID() const
153 return this->source_id;
157 * Gets the ID of the station where the cargo was loaded for the first time.
158 * @return StationID.
160 inline StationID SourceStation() const
162 return this->source;
166 * Gets the coordinates of the cargo's source station.
167 * @return Source station's coordinates.
169 inline TileIndex SourceStationXY() const
171 return this->source_xy;
175 * Gets the coordinates of the cargo's last loading station.
176 * @return Last loading station's coordinates.
178 inline TileIndex LoadedAtXY() const
180 return this->loaded_at_xy;
184 * Gets the ID of station the cargo wants to go next.
185 * @return Next station for this packets.
187 inline StationID NextStation() const
189 return this->next_station;
192 static void InvalidateAllFrom(SourceType src_type, SourceID src);
193 static void InvalidateAllFrom(StationID sid);
194 static void AfterLoad();
198 * Iterate over all _valid_ cargo packets from the given start.
199 * @param var Variable used as "iterator".
200 * @param start Cargo packet ID of the first packet to iterate over.
202 #define FOR_ALL_CARGOPACKETS_FROM(var, start) FOR_ALL_ITEMS_FROM(CargoPacket, cargopacket_index, var, start)
205 * Iterate over all _valid_ cargo packets from the begin of the pool.
206 * @param var Variable used as "iterator".
208 #define FOR_ALL_CARGOPACKETS(var) FOR_ALL_CARGOPACKETS_FROM(var, 0)
211 * Simple collection class for a list of cargo packets.
212 * @tparam Tinst Actual instantiation of this cargo list.
214 template <class Tinst, class Tcont>
215 class CargoList {
216 public:
217 /** The iterator for our container. */
218 typedef typename Tcont::iterator Iterator;
219 /** The reverse iterator for our container. */
220 typedef typename Tcont::reverse_iterator ReverseIterator;
221 /** The const iterator for our container. */
222 typedef typename Tcont::const_iterator ConstIterator;
223 /** The const reverse iterator for our container. */
224 typedef typename Tcont::const_reverse_iterator ConstReverseIterator;
226 /** Kind of actions that could be done with packets on move. */
227 enum MoveToAction {
228 MTA_BEGIN = 0,
229 MTA_TRANSFER = 0, ///< Transfer the cargo to the station.
230 MTA_DELIVER, ///< Deliver the cargo to some town or industry.
231 MTA_KEEP, ///< Keep the cargo in the vehicle.
232 MTA_LOAD, ///< Load the cargo from the station.
233 MTA_END,
234 NUM_MOVE_TO_ACTION = MTA_END
237 protected:
238 uint count; ///< Cache for the number of cargo entities.
239 uint cargo_days_in_transit; ///< Cache for the sum of number of days in transit of each entity; comparable to man-hours.
241 Tcont packets; ///< The cargo packets in this list.
243 void AddToCache(const CargoPacket *cp);
245 void RemoveFromCache(const CargoPacket *cp, uint count);
247 static bool TryMerge(CargoPacket *cp, CargoPacket *icp);
249 public:
250 /** Create the cargo list. */
251 CargoList() {}
253 ~CargoList();
255 void OnCleanPool();
258 * Returns a pointer to the cargo packet list (so you can iterate over it etc).
259 * @return Pointer to the packet list.
261 inline const Tcont *Packets() const
263 return &this->packets;
267 * Returns average number of days in transit for a cargo entity.
268 * @return The before mentioned number.
270 inline uint DaysInTransit() const
272 return this->count == 0 ? 0 : this->cargo_days_in_transit / this->count;
275 void InvalidateCache();
278 typedef std::list<CargoPacket *> CargoPacketList;
281 * CargoList that is used for vehicles.
283 class VehicleCargoList : public CargoList<VehicleCargoList, CargoPacketList> {
284 protected:
285 /** The (direct) parent of this class. */
286 typedef CargoList<VehicleCargoList, CargoPacketList> Parent;
288 Money feeder_share; ///< Cache for the feeder share.
289 uint action_counts[NUM_MOVE_TO_ACTION]; ///< Counts of cargo to be transfered, delivered, kept and loaded.
291 template<class Taction>
292 void ShiftCargo(Taction action);
294 template<class Taction>
295 void PopCargo(Taction action);
298 * Assert that the designation counts add up.
300 inline void AssertCountConsistency() const
302 assert(this->action_counts[MTA_KEEP] +
303 this->action_counts[MTA_DELIVER] +
304 this->action_counts[MTA_TRANSFER] +
305 this->action_counts[MTA_LOAD] == this->count);
308 void AddToCache(const CargoPacket *cp);
309 void RemoveFromCache(const CargoPacket *cp, uint count);
311 void AddToMeta(const CargoPacket *cp, MoveToAction action);
312 void RemoveFromMeta(const CargoPacket *cp, MoveToAction action, uint count);
314 static MoveToAction ChooseAction(const CargoPacket *cp, StationID cargo_next,
315 StationID current_station, bool accepted, StationIDStack next_station);
317 public:
318 /** The station cargo list needs to control the unloading. */
319 friend class StationCargoList;
320 /** The super class ought to know what it's doing. */
321 friend class CargoList<VehicleCargoList, CargoPacketList>;
322 /** The vehicles have a cargo list (and we want that saved). */
323 friend const struct SaveLoad *GetVehicleDescription(VehicleType vt);
325 friend class CargoShift;
326 friend class CargoTransfer;
327 friend class CargoDelivery;
328 template<class Tsource>
329 friend class CargoRemoval;
330 friend class CargoReturn;
331 friend class VehicleCargoReroute;
334 * Returns source of the first cargo packet in this list.
335 * @return The before mentioned source.
337 inline StationID Source() const
339 return this->count == 0 ? INVALID_STATION : this->packets.front()->source;
343 * Returns total sum of the feeder share for all packets.
344 * @return The before mentioned number.
346 inline Money FeederShare() const
348 return this->feeder_share;
352 * Returns the amount of cargo designated for a given purpose.
353 * @param action Action the cargo is designated for.
354 * @return Amount of cargo designated for the given action.
356 inline uint ActionCount(MoveToAction action) const
358 return this->action_counts[action];
362 * Returns sum of cargo on board the vehicle (ie not only
363 * reserved).
364 * @return Cargo on board the vehicle.
366 inline uint StoredCount() const
368 return this->count - this->action_counts[MTA_LOAD];
372 * Returns sum of cargo, including reserved cargo.
373 * @return Sum of cargo.
375 inline uint TotalCount() const
377 return this->count;
381 * Returns sum of reserved cargo.
382 * @return Sum of reserved cargo.
384 inline uint ReservedCount() const
386 return this->action_counts[MTA_LOAD];
390 * Returns sum of cargo to be moved out of the vehicle at the current station.
391 * @return Cargo to be moved.
393 inline uint UnloadCount() const
395 return this->action_counts[MTA_TRANSFER] + this->action_counts[MTA_DELIVER];
399 * Returns the sum of cargo to be kept in the vehicle at the current station.
400 * @return Cargo to be kept or loaded.
402 inline uint RemainingCount() const
404 return this->action_counts[MTA_KEEP] + this->action_counts[MTA_LOAD];
407 void Append(CargoPacket *cp, MoveToAction action = MTA_KEEP);
409 void AgeCargo();
411 void InvalidateCache();
413 void SetTransferLoadPlace(TileIndex xy);
415 bool Stage(bool accepted, StationID current_station, StationIDStack next_station, uint8 order_flags, const GoodsEntry *ge, CargoPayment *payment);
418 * Marks all cargo in the vehicle as to be kept. This is mostly useful for
419 * loading old savegames. When loading is aborted the reserved cargo has
420 * to be returned first.
422 inline void KeepAll()
424 this->action_counts[MTA_DELIVER] = this->action_counts[MTA_TRANSFER] = this->action_counts[MTA_LOAD] = 0;
425 this->action_counts[MTA_KEEP] = this->count;
428 /* Methods for moving cargo around. First parameter is always maximum
429 * amount of cargo to be moved. Second parameter is destination (if
430 * applicable), return value is amount of cargo actually moved. */
432 template<MoveToAction Tfrom, MoveToAction Tto>
433 uint Reassign(uint max_move, TileOrStationID update = INVALID_TILE);
434 uint Return(uint max_move, StationCargoList *dest, StationID next_station);
435 uint Unload(uint max_move, StationCargoList *dest, CargoPayment *payment);
436 uint Shift(uint max_move, VehicleCargoList *dest);
437 uint Truncate(uint max_move = UINT_MAX);
438 uint Reroute(uint max_move, VehicleCargoList *dest, StationID avoid, StationID avoid2, const GoodsEntry *ge);
441 * Are two the two CargoPackets mergeable in the context of
442 * a list of CargoPackets for a Vehicle?
443 * @param cp1 First CargoPacket.
444 * @param cp2 Second CargoPacket.
445 * @return True if they are mergeable.
447 static bool AreMergable(const CargoPacket *cp1, const CargoPacket *cp2)
449 return cp1->source_xy == cp2->source_xy &&
450 cp1->days_in_transit == cp2->days_in_transit &&
451 cp1->source_type == cp2->source_type &&
452 cp1->source_id == cp2->source_id &&
453 cp1->loaded_at_xy == cp2->loaded_at_xy;
457 typedef MultiMap<StationID, CargoPacket *> StationCargoPacketMap;
458 typedef std::map<StationID, uint> StationCargoAmountMap;
461 * CargoList that is used for stations.
463 class StationCargoList : public CargoList<StationCargoList, StationCargoPacketMap> {
464 protected:
465 /** The (direct) parent of this class. */
466 typedef CargoList<StationCargoList, StationCargoPacketMap> Parent;
468 uint reserved_count; ///< Amount of cargo being reserved for loading.
470 public:
471 /** The super class ought to know what it's doing. */
472 friend class CargoList<StationCargoList, StationCargoPacketMap>;
473 /** The stations, via GoodsEntry, have a CargoList. */
474 friend const struct SaveLoad *GetGoodsDesc();
476 friend class CargoLoad;
477 friend class CargoTransfer;
478 template<class Tsource>
479 friend class CargoRemoval;
480 friend class CargoReservation;
481 friend class CargoReturn;
482 friend class StationCargoReroute;
484 static void InvalidateAllFrom(SourceType src_type, SourceID src);
486 template<class Taction>
487 bool ShiftCargo(Taction &action, StationID next);
489 template<class Taction>
490 uint ShiftCargo(Taction action, StationIDStack next, bool include_invalid);
492 void Append(CargoPacket *cp, StationID next);
495 * Check for cargo headed for a specific station.
496 * @param next Station the cargo is headed for.
497 * @return If there is any cargo for that station.
499 inline bool HasCargoFor(StationIDStack next) const
501 while (!next.IsEmpty()) {
502 if (this->packets.find(next.Pop()) != this->packets.end()) return true;
504 /* Packets for INVALID_STTION can go anywhere. */
505 return this->packets.find(INVALID_STATION) != this->packets.end();
509 * Returns source of the first cargo packet in this list.
510 * @return The before mentioned source.
512 inline StationID Source() const
514 return this->count == 0 ? INVALID_STATION : this->packets.begin()->second.front()->source;
518 * Returns sum of cargo still available for loading at the sation.
519 * (i.e. not counting cargo which is already reserved for loading)
520 * @return Cargo on board the vehicle.
522 inline uint AvailableCount() const
524 return this->count;
528 * Returns sum of cargo reserved for loading onto vehicles.
529 * @return Cargo reserved for loading.
531 inline uint ReservedCount() const
533 return this->reserved_count;
537 * Returns total count of cargo at the station, including
538 * cargo which is already reserved for loading.
539 * @return Total cargo count.
541 inline uint TotalCount() const
543 return this->count + this->reserved_count;
546 /* Methods for moving cargo around. First parameter is always maximum
547 * amount of cargo to be moved. Second parameter is destination (if
548 * applicable), return value is amount of cargo actually moved. */
550 uint Reserve(uint max_move, VehicleCargoList *dest, TileIndex load_place, StationIDStack next);
551 uint Load(uint max_move, VehicleCargoList *dest, TileIndex load_place, StationIDStack next);
552 uint Truncate(uint max_move = UINT_MAX, StationCargoAmountMap *cargo_per_source = NULL);
553 uint Reroute(uint max_move, StationCargoList *dest, StationID avoid, StationID avoid2, const GoodsEntry *ge);
556 * Are two the two CargoPackets mergeable in the context of
557 * a list of CargoPackets for a Vehicle?
558 * @param cp1 First CargoPacket.
559 * @param cp2 Second CargoPacket.
560 * @return True if they are mergeable.
562 static bool AreMergable(const CargoPacket *cp1, const CargoPacket *cp2)
564 return cp1->source_xy == cp2->source_xy &&
565 cp1->days_in_transit == cp2->days_in_transit &&
566 cp1->source_type == cp2->source_type &&
567 cp1->source_id == cp2->source_id;
571 #endif /* CARGOPACKET_H */