(svn r26892) -Feature: Script API for retrieving planned flow

bin/ai/regression/regression.nut

@@ -1269,6 +1269,25 @@ function Regression::Station()
 		}
 	}
 
+	print("");
+	print("--CargoPlanned--");
+	for (local cargo = 0; cargo <= 1000; cargo += 1000) {
+		for (local station0 = 0; station0 <= 1000; station0 += 1000) {
+			print("  GetCargoPlanned(" + station0 + ", " + cargo + "): " +
+					AIStation.GetCargoPlanned(station0, cargo));
+			for (local station1 = 0; station1 <= 1000; station1 += 1000) {
+				print("  GetCargoPlannedFrom(" + station0 + ", " + station1 + ", " + cargo + "): " +
+						AIStation.GetCargoPlannedFrom(station0, station1, cargo));
+				print("  GetCargoPlannedVia(" + station0 + ", " + station1 + ", " + cargo + "): " +
+						AIStation.GetCargoPlannedFrom(station0, station1, cargo));
+				for (local station2 = 0; station2 <= 1000; station2 += 1000) {
+					print("  GetCargoPlannedFromVia(" + station0 + ", " + station1 + ", " + station2 + ", " + cargo + "): " +
+							AIStation.GetCargoPlannedFromVia(station0, station1, station2, cargo));
+				}
+			}
+		}
+	}
+
 	local list = AIStationList(AIStation.STATION_BUS_STOP + AIStation.STATION_TRUCK_STOP);
 
 	print("");

bin/ai/regression/regression.txt

@@ -7539,6 +7539,44 @@ ERROR: IsEnd() is invalid as Begin() is never called
   GetCargoWaitingFromVia(1000, 1000, 0, 1000): -1
   GetCargoWaitingFromVia(1000, 1000, 1000, 1000): -1
 
+--CargoPlanned--
+  GetCargoPlanned(0, 0): 0
+  GetCargoPlannedFrom(0, 0, 0): 0
+  GetCargoPlannedVia(0, 0, 0): 0
+  GetCargoPlannedFromVia(0, 0, 0, 0): 0
+  GetCargoPlannedFromVia(0, 0, 1000, 0): -1
+  GetCargoPlannedFrom(0, 1000, 0): -1
+  GetCargoPlannedVia(0, 1000, 0): -1
+  GetCargoPlannedFromVia(0, 1000, 0, 0): -1
+  GetCargoPlannedFromVia(0, 1000, 1000, 0): -1
+  GetCargoPlanned(1000, 0): -1
+  GetCargoPlannedFrom(1000, 0, 0): -1
+  GetCargoPlannedVia(1000, 0, 0): -1
+  GetCargoPlannedFromVia(1000, 0, 0, 0): -1
+  GetCargoPlannedFromVia(1000, 0, 1000, 0): -1
+  GetCargoPlannedFrom(1000, 1000, 0): -1
+  GetCargoPlannedVia(1000, 1000, 0): -1
+  GetCargoPlannedFromVia(1000, 1000, 0, 0): -1
+  GetCargoPlannedFromVia(1000, 1000, 1000, 0): -1
+  GetCargoPlanned(0, 1000): -1
+  GetCargoPlannedFrom(0, 0, 1000): -1
+  GetCargoPlannedVia(0, 0, 1000): -1
+  GetCargoPlannedFromVia(0, 0, 0, 1000): -1
+  GetCargoPlannedFromVia(0, 0, 1000, 1000): -1
+  GetCargoPlannedFrom(0, 1000, 1000): -1
+  GetCargoPlannedVia(0, 1000, 1000): -1
+  GetCargoPlannedFromVia(0, 1000, 0, 1000): -1
+  GetCargoPlannedFromVia(0, 1000, 1000, 1000): -1
+  GetCargoPlanned(1000, 1000): -1
+  GetCargoPlannedFrom(1000, 0, 1000): -1
+  GetCargoPlannedVia(1000, 0, 1000): -1
+  GetCargoPlannedFromVia(1000, 0, 0, 1000): -1
+  GetCargoPlannedFromVia(1000, 0, 1000, 1000): -1
+  GetCargoPlannedFrom(1000, 1000, 1000): -1
+  GetCargoPlannedVia(1000, 1000, 1000): -1
+  GetCargoPlannedFromVia(1000, 1000, 0, 1000): -1
+  GetCargoPlannedFromVia(1000, 1000, 1000, 1000): -1
+
 --StationList--
   Count():             2
   Location ListDump:

src/script/api/ai/ai_station.hpp.sq

@@ -50,6 +50,10 @@ void SQAIStation_Register(Squirrel *engine)
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingFrom,        "GetCargoWaitingFrom",        4, ".iii");
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingVia,         "GetCargoWaitingVia",         4, ".iii");
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingFromVia,     "GetCargoWaitingFromVia",     5, ".iiii");
+	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlanned,            "GetCargoPlanned",            3, ".ii");
+	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedFrom,        "GetCargoPlannedFrom",        4, ".iii");
+	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedVia,         "GetCargoPlannedVia",         4, ".iii");
+	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedFromVia,     "GetCargoPlannedFromVia",     5, ".iiii");
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::HasCargoRating,             "HasCargoRating",             3, ".ii");
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoRating,             "GetCargoRating",             3, ".ii");
 	SQAIStation.DefSQStaticMethod(engine, &ScriptStation::GetCoverageRadius,          "GetCoverageRadius",          2, ".i");

src/script/api/ai_changelog.hpp

@@ -20,6 +20,10 @@
  * 1.5.0 is not yet released. The following changes are not set in stone yet.
  *
  * API additions:
+ * \li AIStation::GetCargoPlanned
+ * \li AIStation::GetCargoPlannedFrom
+ * \li AIStation::GetCargoPlannedFromVia
+ * \li AIStation::GetCargoPlannedVia
  * \li AIStation::GetCargoWaitingFromVia
  *
  * \b 1.4.2

src/script/api/game/game_station.hpp.sq

@@ -51,6 +51,10 @@ void SQGSStation_Register(Squirrel *engine)
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingFrom,        "GetCargoWaitingFrom",        4, ".iii");
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingVia,         "GetCargoWaitingVia",         4, ".iii");
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoWaitingFromVia,     "GetCargoWaitingFromVia",     5, ".iiii");
+	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlanned,            "GetCargoPlanned",            3, ".ii");
+	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedFrom,        "GetCargoPlannedFrom",        4, ".iii");
+	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedVia,         "GetCargoPlannedVia",         4, ".iii");
+	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoPlannedFromVia,     "GetCargoPlannedFromVia",     5, ".iiii");
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::HasCargoRating,             "HasCargoRating",             3, ".ii");
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCargoRating,             "GetCargoRating",             3, ".ii");
 	SQGSStation.DefSQStaticMethod(engine, &ScriptStation::GetCoverageRadius,          "GetCoverageRadius",          2, ".i");

src/script/api/game_changelog.hpp

@@ -20,6 +20,10 @@
  * 1.5.0 is not yet released. The following changes are not set in stone yet.
  *
  * API additions:
+ * \li GSStation::GetCargoPlanned
+ * \li GSStation::GetCargoPlannedFrom
+ * \li GSStation::GetCargoPlannedFromVia
+ * \li GSStation::GetCargoPlannedVia
  * \li GSStation::GetCargoWaitingFromVia
  *
  * \b 1.4.2

src/script/api/script_station.cpp

@@ -39,14 +39,25 @@
 	return ::GetStationIndex(tile);
 }
 
+template<bool Tfrom, bool Tvia>
+/* static */ bool ScriptStation::IsCargoRequestValid(StationID station_id,
+		StationID from_station_id, StationID via_station_id, CargoID cargo_id)
+{
+	if (!IsValidStation(station_id)) return false;
+	if (Tfrom && !IsValidStation(from_station_id) && from_station_id != STATION_INVALID) return false;
+	if (Tvia && !IsValidStation(via_station_id) && via_station_id != STATION_INVALID) return false;
+	if (!ScriptCargo::IsValidCargo(cargo_id)) return false;
+	return true;
+}
+
 template<bool Tfrom, bool Tvia>
 /* static */ int32 ScriptStation::CountCargoWaiting(StationID station_id,
 		StationID from_station_id, StationID via_station_id, CargoID cargo_id)
 {
-	if (!IsValidStation(station_id)) return -1;
+	if (!ScriptStation::IsCargoRequestValid<Tfrom, Tvia>(station_id, from_station_id,
-	if (Tfrom && !IsValidStation(from_station_id) && from_station_id != STATION_INVALID) return -1;
+			via_station_id, cargo_id)) {
-	if (Tvia && !IsValidStation(via_station_id) && via_station_id != STATION_INVALID) return -1;
+		return -1;
-	if (!ScriptCargo::IsValidCargo(cargo_id)) return -1;
+	}
 
 	const StationCargoList &cargo_list = ::Station::Get(station_id)->goods[cargo_id].cargo;
 	if (!Tfrom && !Tvia) return cargo_list.TotalCount();
@@ -87,6 +98,47 @@ template<bool Tfrom, bool Tvia>
 	return CountCargoWaiting<true, true>(station_id, from_station_id, via_station_id, cargo_id);
 }
 
+template<bool Tfrom, bool Tvia>
+/* static */ int32 ScriptStation::CountCargoPlanned(StationID station_id,
+		StationID from_station_id, StationID via_station_id, CargoID cargo_id)
+{
+	if (!ScriptStation::IsCargoRequestValid<Tfrom, Tvia>(station_id, from_station_id,
+			via_station_id, cargo_id)) {
+		return -1;
+	}
+
+	const FlowStatMap &flows = ::Station::Get(station_id)->goods[cargo_id].flows;
+	if (Tfrom) {
+		return Tvia ? flows.GetFlowFromVia(from_station_id, via_station_id) :
+					  flows.GetFlowFrom(from_station_id);
+	} else {
+		return Tvia ? flows.GetFlowVia(via_station_id) : flows.GetFlow();
+	}
+}
+
+/* static */ int32 ScriptStation::GetCargoPlanned(StationID station_id, CargoID cargo_id)
+{
+	return CountCargoPlanned<false, false>(station_id, STATION_INVALID, STATION_INVALID, cargo_id);
+}
+
+/* static */ int32 ScriptStation::GetCargoPlannedFrom(StationID station_id,
+		StationID from_station_id, CargoID cargo_id)
+{
+	return CountCargoPlanned<true, false>(station_id, from_station_id, STATION_INVALID, cargo_id);
+}
+
+/* static */ int32 ScriptStation::GetCargoPlannedVia(StationID station_id,
+		StationID via_station_id, CargoID cargo_id)
+{
+	return CountCargoPlanned<false, true>(station_id, STATION_INVALID, via_station_id, cargo_id);
+}
+
+/* static */ int32 ScriptStation::GetCargoPlannedFromVia(StationID station_id,
+		StationID from_station_id, StationID via_station_id, CargoID cargo_id)
+{
+	return CountCargoPlanned<true, true>(station_id, from_station_id, via_station_id, cargo_id);
+}
+
 /* static */ bool ScriptStation::HasCargoRating(StationID station_id, CargoID cargo_id)
 {
 	if (!IsValidStation(station_id)) return false;

src/script/api/script_station.hpp

@@ -127,6 +127,58 @@ public:
 	 */
 	static int32 GetCargoWaitingFromVia(StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id);
 
+	/**
+	 * See how much cargo was planned to pass (including production and consumption) this station per month.
+	 * @param station_id The station to get the planned flow for.
+	 * @param cargo_id The cargo type to get the planned flow for.
+	 * @pre IsValidStation(station_id).
+	 * @pre IsValidCargo(cargo_id).
+	 * @return The amount of cargo units planned to pass the station per month.
+	 */
+	static int32 GetCargoPlanned(StationID station_id, CargoID cargo_id);
+
+	/**
+	 * See how much cargo from the specified origin was planned to pass (including production and consumption) this station per month.
+	 * @param station_id The station to get the planned flow for.
+	 * @param from_station_id The station the cargo originates at.
+	 * @param cargo_id The cargo type to get the planned flow for.
+	 * @pre IsValidStation(station_id).
+	 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
+	 * @pre IsValidCargo(cargo_id).
+	 * @return The amount of cargo units from the specified origin planned to pass the station per month.
+	 */
+	static int32 GetCargoPlannedFrom(StationID station_id, StationID from_station_id, CargoID cargo_id);
+
+	/**
+	 * See how much cargo was planned to pass (including production and consumption) this station per month, heading for the specified next hop.
+	 * @param station_id The station to get the planned flow for.
+	 * @param via_station_id The next station the cargo will go on to.
+	 * @param cargo_id The cargo type to get the planned flow for.
+	 * @pre IsValidStation(station_id).
+	 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
+	 * @pre IsValidCargo(cargo_id).
+	 * @return The amount of cargo units planned to pass the station per month, going via the specified next hop.
+	 * @note Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.
+	 */
+	static int32 GetCargoPlannedVia(StationID station_id, StationID via_station_id, CargoID cargo_id);
+
+	/**
+	 * See how much cargo from the specified origin was planned to pass this station per month,
+	 * heading for the specified next hop.
+	 * @param station_id The station to get the planned flow for.
+	 * @param from_station_id The station the cargo originates at.
+	 * @param via_station_id The next station the cargo will go on to.
+	 * @param cargo_id The cargo type to get the planned flow for.
+	 * @pre IsValidStation(station_id).
+	 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
+	 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
+	 * @pre IsValidCargo(cargo_id).
+	 * @return The amount of cargo units from the specified origin planned to pass the station per month, going via the specified next hop.
+	 * @note Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.
+	 * @note Cargo planned to pass "from" the same station that's being queried is actually produced there.
+	 */
+	static int32 GetCargoPlannedFromVia(StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id);
+
 	/**
 	 * Check whether the given cargo at the given station a rating.
 	 * @param station_id The station to get the cargo-rating state of.
@@ -244,10 +296,18 @@ public:
 	static bool OpenCloseAirport(StationID station_id);
 
 private:
+	template<bool Tfrom, bool Tvia>
+	static bool IsCargoRequestValid(StationID station_id, StationID from_station_id,
+			StationID via_station_id, CargoID cargo_id);
+
 	template<bool Tfrom, bool Tvia>
 	static int32 CountCargoWaiting(StationID station_id, StationID from_station_id,
 			StationID via_station_id, CargoID cargo_id);
 
+	template<bool Tfrom, bool Tvia>
+	static int32 CountCargoPlanned(StationID station_id, StationID from_station_id,
+			StationID via_station_id, CargoID cargo_id);
+
 };
 
 DECLARE_ENUM_AS_BIT_SET(ScriptStation::StationType)