/* $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:
	/**
	 * The name of the class, needed by several sub-processes.
	 */
	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.
	 */
	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.
	 */
	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 town_id has to be valid (use IsValidTown()).
	 * @return the name of the town.
	 * @note the returned name must be free'd (C++ only).
	 */
	static char *GetName(TownID town_id);

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

	/**
	 * Gets the location of the town.
	 * @param town_id the location of the town.
	 * @pre town_id has to be valid (use IsValidTown()).
	 * @return the location of the town.
	 * @post return value is always positive and below AIMap::GetMapSize().
	 */
	static TileIndex GetLocation(TownID town_id);
};

#endif /* AI_TOWN_HPP */