Add AI/GS method to get annual expense category value

See: #425

docs/script-additions.html

@@ -96,6 +96,26 @@
 		</div>
 	</div>
 
+	<h3>Company: <a href="https://docs.openttd.org/gs-api/classGSCompany.html">GSCompany Class</a> and <a href="https://docs.openttd.org/ai-api/classAICompany.html">AICompany Class</a></h3>
+	<div class="indent">
+		<h4>Additional Static Public Member Functions:</h4>
+		<div class="indent">
+			<div class="code">static bool GetAnnualExpenseValue (CompanyID company, uint32 year_offset, ExpensesType expenses_type)</div>
+			<div class="methodtext">Get the annual expense value for the given company.</div>
+			<div class="methodtext">year_offset is relative to the current year and must be either: 0, 1, or 2.</div>
+		</div>
+		<h4>Additional Enum Values:</h4>
+		<div class="indent">
+
+			<div class="code">ExpensesType</div>
+			<div>Additional value: <span class="code">EXPENSES_SHARING_COST</span></div>
+			<div class="methodtext">Infrastructure sharing costs.</div>
+			<div>Additional value: <span class="code">EXPENSES_SHARING_INC</span></div>
+			<div class="methodtext">Infrastructure sharing income.</div>
+			<div>ExpensesType is additionally available via AICompany.</div>
+		</div>
+	</div>
+
 	<h3>Inflation: GSInflation Class and AIInflation Class</h3>
 	<div class="indent">
 		<h4>Static Public Member Functions:</h4>

src/script/api/script_company.cpp

@@ -167,6 +167,17 @@
 	return ::Company::Get(company)->old_economy[quarter - 1].company_value;
 }
 
+/* static */ Money ScriptCompany::GetAnnualExpenseValue(CompanyID company, uint32 year_offset, ExpensesType expenses_type)
+{
+	EnforcePrecondition(false, expenses_type < (ExpensesType)::EXPENSES_END);
+	EnforcePrecondition(false, year_offset <= 2);
+
+	company = ResolveCompanyID(company);
+	if (company == COMPANY_INVALID) return -1;
+
+	return ::Company::Get(company)->yearly_expenses[year_offset][expenses_type];
+}
+
 
 /* static */ Money ScriptCompany::GetBankBalance(ScriptCompany::CompanyID company)
 {

src/script/api/script_company.hpp

@@ -97,7 +97,6 @@ public:
 
 	/**
 	 * Types of expenses.
-	 * @api -ai
 	 */
 	enum ExpensesType : byte {
 		EXPENSES_CONSTRUCTION = ::EXPENSES_CONSTRUCTION,     ///< Construction costs.
@@ -113,6 +112,8 @@ public:
 		EXPENSES_SHIP_INC     = ::EXPENSES_SHIP_REVENUE,     ///< Revenue from ships.
 		EXPENSES_LOAN_INT     = ::EXPENSES_LOAN_INTEREST,    ///< Interest payments over the loan.
 		EXPENSES_OTHER        = ::EXPENSES_OTHER,            ///< Other expenses.
+		EXPENSES_SHARING_COST = ::EXPENSES_SHARING_COST,     ///< Infrastructure sharing costs.
+		EXPENSES_SHARING_INC  = ::EXPENSES_SHARING_INC,      ///< Infrastructure sharing income.
 		EXPENSES_INVALID      = ::INVALID_EXPENSES,          ///< Invalid expense type.
 	};
 
@@ -310,6 +311,17 @@ public:
 	 */
 	static Money GetQuarterlyCompanyValue(CompanyID company, uint32 quarter);
 
+	/**
+	 * Get the expense category value of the company in the given year (relative to the current year).
+	 * @param company The company to get the value of.
+	 * @param year_offset The year, relative to the current year (value values are 0, 1, and 2).
+	 * @param expenses_type The expense category to return.
+	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
+	 * @pre year_offset <= 2.
+	 * @return The value of the company in the given quarter.
+	 */
+	static Money GetAnnualExpenseValue(CompanyID company, uint32 year_offset, ExpensesType expenses_type);
+
 	/**
 	 * Build your company's HQ on the given tile.
 	 * @param tile The tile to build your HQ on, this tile is the most northern tile of your HQ.