diff options
Diffstat (limited to 'src/cargopacket.cpp')
-rw-r--r-- | src/cargopacket.cpp | 87 |
1 files changed, 85 insertions, 2 deletions
diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp index 418eb8e83..e73341ff3 100644 --- a/src/cargopacket.cpp +++ b/src/cargopacket.cpp @@ -25,14 +25,26 @@ void InitializeCargoPackets() _cargopacket_pool.CleanPool(); } +/** + * Create a new packet for savegame loading. + */ CargoPacket::CargoPacket() { this->source_type = ST_INDUSTRY; this->source_id = INVALID_SOURCE; } -/* NOTE: We have to zero memory ourselves here because we are using a 'new' - * that, in contrary to all other pools, does not memset to 0. */ +/** + * Creates a new cargo packet + * @param source the source station of the packet + * @param source_xy the source location of the packet + * @param count the number of cargo entities to put in this packet + * @param source_type the 'type' of source the packet comes from (for subsidies) + * @param source_id the actual source of the packet (for subsidies) + * @pre count != 0 + * @note We have to zero memory ourselves here because we are using a 'new' + * that, in contrary to all other pools, does not memset to 0. + */ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id) : feeder_share(0), count(count), @@ -46,6 +58,18 @@ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, So this->source_type = source_type; } +/** + * Creates a new cargo packet. Initializes the fields that cannot be changed later. + * Used when loading or splitting packets. + * @param count the number of cargo entities to put in this packet + * @param days_in_transit number of days the cargo has been in transit + * @param source the station the cargo was initially loaded + * @param source_xy the station location the cargo was initially loaded + * @param loaded_at_xy the location the cargo was loaded last + * @param feeder_share feeder share the packet has already accumulated + * @param source_type the 'type' of source the packet comes from (for subsidies) + * @param source_id the actual source of the packet (for subsidies) + */ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share, SourceType source_type, SourceID source_id) : feeder_share(feeder_share), count(count), @@ -90,6 +114,7 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T * */ +/** Destroy it ("frees" all cargo packets) */ template <class Tinst> CargoList<Tinst>::~CargoList() { @@ -98,6 +123,11 @@ CargoList<Tinst>::~CargoList() } } +/** + * Update the cached values to reflect the removal of this packet. + * Decreases count and days_in_transit + * @param cp Packet to be removed from cache + */ template <class Tinst> void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp) { @@ -105,6 +135,11 @@ void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp) this->cargo_days_in_transit -= cp->days_in_transit * cp->count; } +/** + * Update the cache to reflect adding of this packet. + * Increases count and days_in_transit + * @param cp a new packet to be inserted + */ template <class Tinst> void CargoList<Tinst>::AddToCache(const CargoPacket *cp) { @@ -112,6 +147,13 @@ void CargoList<Tinst>::AddToCache(const CargoPacket *cp) this->cargo_days_in_transit += cp->days_in_transit * cp->count; } +/** + * Appends the given cargo packet + * @warning After appending this packet may not exist anymore! + * @note Do not use the cargo packet anymore after it has been appended to this CargoList! + * @param cp the cargo packet to add + * @pre cp != NULL + */ template <class Tinst> void CargoList<Tinst>::Append(CargoPacket *cp) { @@ -134,6 +176,11 @@ void CargoList<Tinst>::Append(CargoPacket *cp) } +/** + * Truncates the cargo in this list to the given amount. It leaves the + * first count cargo entities and removes the rest. + * @param max_remaining the maximum amount of entities to be in the list after the command + */ template <class Tinst> void CargoList<Tinst>::Truncate(uint max_remaining) { @@ -161,6 +208,27 @@ void CargoList<Tinst>::Truncate(uint max_remaining) } } +/** + * Moves the given amount of cargo to another list. + * Depending on the value of mta the side effects of this function differ: + * - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station + * - MTA_CARGO_LOAD: sets the loaded_at_xy value of the moved packets + * - MTA_TRANSFER: just move without side effects + * - MTA_UNLOAD: just move without side effects + * @param dest the destination to move the cargo to + * @param count the amount of cargo entities to move + * @param mta how to handle the moving (side effects) + * @param data Depending on mta the data of this variable differs: + * - MTA_FINAL_DELIVERY - station ID of packet's origin not to remove + * - MTA_CARGO_LOAD - station's tile index of load + * - MTA_TRANSFER - unused + * - MTA_UNLOAD - unused + * @param payment The payment helper + * + * @pre mta == MTA_FINAL_DELIVERY || dest != NULL + * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL + * @return true if there are still packets that might be moved from this cargo list + */ template <class Tinst> template <class Tother_inst> bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta, CargoPayment *payment, uint data) @@ -240,6 +308,7 @@ bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta return it != packets.end(); } +/** Invalidates the cached data and rebuild it */ template <class Tinst> void CargoList<Tinst>::InvalidateCache() { @@ -252,18 +321,31 @@ void CargoList<Tinst>::InvalidateCache() } +/** + * Update the cached values to reflect the removal of this packet. + * Decreases count, feeder share and days_in_transit + * @param cp Packet to be removed from cache + */ void VehicleCargoList::RemoveFromCache(const CargoPacket *cp) { this->feeder_share -= cp->feeder_share; this->Parent::RemoveFromCache(cp); } +/** + * Update the cache to reflect adding of this packet. + * Increases count, feeder share and days_in_transit + * @param cp a new packet to be inserted + */ void VehicleCargoList::AddToCache(const CargoPacket *cp) { this->feeder_share += cp->feeder_share; this->Parent::AddToCache(cp); } +/** + * Ages the all cargo in this list + */ void VehicleCargoList::AgeCargo() { for (ConstIterator it(this->packets.begin()); it != this->packets.end(); it++) { @@ -276,6 +358,7 @@ void VehicleCargoList::AgeCargo() } } +/** Invalidates the cached data and rebuild it */ void VehicleCargoList::InvalidateCache() { this->feeder_share = 0; |