/* $Id$ */

/** @file ai_town.hpp Everything to query towns. */

#ifndef AI_TOWN_HPP
#define AI_TOWN_HPP

#include "ai_object.hpp"

/**
 * Class that handles all town related functions.
 */
class AITown : public AIObject {
public:
	static const char *GetClassName() { return "AITown"; }

	/**
	 * Gets the maximum town index; there are no valid towns with a higher index.
	 * @return The maximum town index.
	 * @post Return value is always non-negative.
	 */
	static TownID GetMaxTownID();

	/**
	 * Gets the number of towns. This is different than GetMaxTownID()
	 *   because of the way OpenTTD works internally.
	 * @return The number of towns.
	 * @post Return value is always non-negative.
	 */
	static int32 GetTownCount();

	/**
	 * Checks whether the given town index is valid.
	 * @param town_id The index to check.
	 * @return True if and only if the town is valid.
	 */
	static bool IsValidTown(TownID town_id);

	/**
	 * Get the name of the town.
	 * @param town_id The town to get the name of.
	 * @pre IsValidTown(town_id).
	 * @return The name of the town.
	 */
	static char *GetName(TownID town_id);

	/**
	 * Gets the number of inhabitants in the town.
	 * @param town_id The town to get the population of.
	 * @pre IsValidTown(town_id).
	 * @return The number of inhabitants.
	 * @post Return value is always non-negative.
	 */
	static int32 GetPopulation(TownID town_id);

	/**
	 * Gets the number of houses in the town.
	 * @param town_id The town to get the number of houses of.
	 * @pre IsValidTown(town_id).
	 * @return The number of houses.
	 * @post Return value is always non-negative.
	 */
	static int32 GetNumHouses(TownID town_id);

	/**
	 * Gets the location of the town.
	 * @param town_id The town to get the location of.
	 * @pre IsValidTown(town_id).
	 * @return The location of the town.
	 */
	static TileIndex GetLocation(TownID town_id);

	/**
	 * Get the total last month's production of the given cargo at a town.
	 * @param town_id The index of the town.
	 * @param cargo_id The index of the cargo.
	 * @pre IsValidTown(town_id).
	 * @pre AICargo::IsValidCargo(cargo_id).
	 * @pre AICargo::GetTownEffect(cargo_id) == TE_PASSENGERS || AICargo::GetTownEffect(cargo_id) == TE_MAIL.
	 * @return The last month's production of the given cargo for this town.
	 * @post Return value is always non-negative.
	 */
	static int32 GetLastMonthProduction(TownID town_id, CargoID cargo_id);

	/**
	 * Get the total amount of cargo transported from a town last month.
	 * @param town_id The index of the industry.
	 * @param cargo_id The index of the cargo.
	 * @pre IsValidTown(town_id).
	 * @pre AICargo::IsValidCargo(cargo_id).
	 * @pre AICargo::GetTownEffect(cargo_id) == TE_PASSENGERS || AICargo::GetTownEffect(cargo_id) == TE_MAIL.
	 * @return The amount of given cargo transported from this town last month.
	 * @post Return value is always non-negative.
	 */
	static int32 GetLastMonthTransported(TownID town_id, CargoID cargo_id);

	/**
	 * Get the maximum production of the given cargo at a town.
	 * @param town_id The index of the town.
	 * @param cargo_id The index of the cargo.
	 * @pre IsValidTown(town_id).
	 * @pre AICargo::IsValidCargo(cargo_id).
	 * @pre AICargo::GetTownEffect(cargo_id) == TE_PASSENGERS || AICargo::GetTownEffect(cargo_id) == TE_MAIL.
	 * @return The maximum production of the given cargo for this town.
	 * @post Return value is always non-negative.
	 */
	static int32 GetMaxProduction(TownID town_id, CargoID cargo_id);

	/**
	 * Get the manhattan distance from the tile to the AITown::GetLocation()
	 *  of the town.
	 * @param town_id The town to get the distance to.
	 * @param tile The tile to get the distance to.
	 * @pre IsValidTown(town_id).
	 * @return The distance between town and tile.
	 */
	static int32 GetDistanceManhattanToTile(TownID town_id, TileIndex tile);

	/**
	 * Get the square distance from the tile to the AITown::GetLocation()
	 *  of the town.
	 * @param town_id The town to get the distance to.
	 * @param tile The tile to get the distance to.
	 * @pre IsValidTown(town_id).
	 * @return The distance between town and tile.
	 */
	static int32 GetDistanceSquareToTile(TownID town_id, TileIndex tile);

	/**
	 * Find out if this tile is within the rating influence of a town.
	 *  Stations on this tile influence the rating of the town.
	 * @param town_id The town to check.
	 * @param tile The tile to check.
	 * @return True if the tile is within the rating influence of the town.
	 */
	static bool IsWithinTownInfluence(TownID town_id, TileIndex tile);
};

#endif /* AI_TOWN_HPP */