Add vehicle function to get first vehicle in tile hash for tile

src/vehicle.cpp

@@ -581,6 +581,25 @@ Vehicle *VehicleFromPos(TileIndex tile, VehicleType type, void *data, VehicleFro
 	return nullptr;
 }
 
+/**
+ * Returns the first vehicle on a specific location, this should be iterated using Vehicle::HashTileNext.
+ * @note Use #GetFirstVehicleOnPos when you have the intention that all vehicles should be iterated over using Vehicle::HashTileNext. The iteration order is non-deterministic.
+ * @param tile The location on the map
+ * @param type The vehicle type
+ * @return First vehicle or nullptr.
+ */
+Vehicle *GetFirstVehicleOnPos(TileIndex tile, VehicleType type)
+{
+	VehicleTypeTileHash &vhash = _vehicle_tile_hashes[type];
+
+	auto iter = vhash.find(tile);
+	if (iter != vhash.end()) {
+		return Vehicle::Get(iter->second);
+	} else {
+		return nullptr;
+	}
+}
+
 /**
  * Callback that returns 'real' vehicles lower or at height \c *(int*)data .
  * @param v Vehicle to examine.

src/vehicle_base.h

@@ -793,6 +793,12 @@ public:
 		return v;
 	}
 
+	/**
+	 * Get the next vehicle in the tile hash chain.
+	 * @return the next vehicle in the tile hash chain or nullptr when there isn't a next vehicle.
+	 */
+	inline Vehicle *HashTileNext() const { return this->hash_tile_next; }
+
 	/**
 	 * Get the vehicle at offset \a n of this vehicle chain.
 	 * @param n Offset from the current vehicle.
@@ -1495,6 +1501,12 @@ struct SpecializedVehicle : public Vehicle {
 	 */
 	inline T *GetPrevVehicle() const { return (T *)this->Vehicle::GetPrevVehicle(); }
 
+	/**
+	 * Get the next vehicle in the tile hash chain.
+	 * @return the next vehicle in the tile hash chain or nullptr when there isn't a next vehicle.
+	 */
+	inline T *HashTileNext() const { return (T *)this->Vehicle::HashTileNext(); }
+
 	/**
 	 * Tests whether given index is a valid index for vehicle of this type
 	 * @param index tested index

src/vehicle_func.h

@@ -82,6 +82,8 @@ inline bool HasVehicleOnPos(TileIndex tile, VehicleType type, void *data, Vehicl
 	return VehicleFromPos(tile, type, data, proc, true) != nullptr;
 }
 
+Vehicle *GetFirstVehicleOnPos(TileIndex tile, VehicleType type);
+
 /**
  * Find a vehicle from a specific location. It will call proc for ALL vehicles
  * on the tile and YOU must make SURE that the "best one" is stored in the