(svn r18204) -Codechange: introduce a type for Ticks and use it; furthermore document some related variables/functions

src/date_type.h

@@ -50,12 +50,13 @@ enum {
  * be encoded in a single 32 bits date, about 2^31 / 366 years. */
 #define MAX_YEAR 5000000
 
-typedef int32  Date;
-typedef uint16 DateFract;
+typedef int32  Date;      ///< The type to store our dates in
+typedef uint16 DateFract; ///< The fraction of a date we're in, i.e. the number of ticks since the last date changeover
+typedef int32  Ticks;     ///< The type to store ticks in
 
-typedef int32  Year;
-typedef uint8  Month;
-typedef uint8  Day;
+typedef int32  Year;  ///< Type for the year, note: 0 based, i.e. starts at the year 0.
+typedef uint8  Month; ///< Type for the month, note: 0 based, i.e. 0 = January, 11 = December.
+typedef uint8  Day;   ///< Type for the day of the month, note: 1 based, first day of a month is 1.
 
 /**
  * Data structure to convert between Date and triplet (year, month, and day).
@@ -67,7 +68,8 @@ struct YearMonthDay {
 	Day   day;    ///< Day (1..31)
 };
 
-static const Year INVALID_YEAR = -1;
-static const Date INVALID_DATE = -1;
+static const Year  INVALID_YEAR  = -1; ///< Representation of an invalid year
+static const Date  INVALID_DATE  = -1; ///< Representation of an invalid date
+static const Ticks INVALID_TICKS = -1; ///< Representation of an invalid number of ticks
 
 #endif /* DATE_TYPE_H */

src/order_base.h

@@ -19,6 +19,7 @@
 #include "depot_type.h"
 #include "station_type.h"
 #include "vehicle_type.h"
+#include "date_type.h"
 
 typedef Pool<Order, OrderID, 256, 64000> OrderPool;
 typedef Pool<OrderList, OrderListID, 128, 64000> OrderListPool;
@@ -265,7 +266,7 @@ private:
 	uint num_vehicles;              ///< NOSAVE: Number of vehicles that share this order list
 	Vehicle *first_shared;          ///< NOSAVE: pointer to the first vehicle in the shared order chain
 
-	uint timetable_duration;        ///< NOSAVE: Total duration of the order list
+	Ticks timetable_duration;       ///< NOSAVE: Total duration of the order list
 
 public:
 	/** Default constructor producing an invalid order list. */
@@ -384,22 +385,22 @@ public:
 	bool IsCompleteTimetable() const;
 
 	/**
-	 * Gets the total duration of the vehicles timetable or -1 is the timetable is not complete.
-	 * @return total timetable duration or -1 for incomplete timetables
+	 * Gets the total duration of the vehicles timetable or INVALID_TICKS is the timetable is not complete.
+	 * @return total timetable duration or INVALID_TICKS for incomplete timetables
 	 */
-	inline int GetTimetableTotalDuration() const { return this->IsCompleteTimetable() ? (int)this->timetable_duration : -1; }
+	inline Ticks GetTimetableTotalDuration() const { return this->IsCompleteTimetable() ? this->timetable_duration : INVALID_TICKS; }
 
 	/**
 	 * Gets the known duration of the vehicles timetable even if the timetable is not complete.
 	 * @return known timetable duration
 	 */
-	inline int GetTimetableDurationIncomplete() const { return this->timetable_duration; }
+	inline Ticks GetTimetableDurationIncomplete() const { return this->timetable_duration; }
 
 	/**
 	 * Must be called if an order's timetable is changed to update internal book keeping.
 	 * @param delta By how many ticks has the timetable duration changed
 	 */
-	void UpdateOrderTimetable(int delta) { this->timetable_duration += delta; }
+	void UpdateOrderTimetable(Ticks delta) { this->timetable_duration += delta; }
 
 	/**
 	 * Free a complete order chain.

src/order_cmd.cpp

@@ -362,7 +362,7 @@ void OrderList::DebugCheckSanity() const
 {
 	VehicleOrderID check_num_orders = 0;
 	uint check_num_vehicles = 0;
-	uint check_timetable_duration = 0;
+	Ticks check_timetable_duration = 0;
 
 	DEBUG(misc, 6, "Checking OrderList %hu for sanity...", this->index);
 
@@ -378,7 +378,7 @@ void OrderList::DebugCheckSanity() const
 		assert(v->orders.list == this);
 	}
 	assert(this->num_vehicles == check_num_vehicles);
-	DEBUG(misc, 6, "... detected %u orders, %u vehicles, %u ticks", (uint)this->num_orders,
+	DEBUG(misc, 6, "... detected %u orders, %u vehicles, %i ticks", (uint)this->num_orders,
 	      this->num_vehicles, this->timetable_duration);
 }
 

src/timetable.h

@@ -12,8 +12,10 @@
 #ifndef TIMETABLE_H
 #define TIMETABLE_H
 
+#include "date_type.h"
+
 void ShowTimetableWindow(const Vehicle *v);
 void UpdateVehicleTimetable(Vehicle *v, bool travelling);
-void SetTimetableParams(int param1, int param2, uint32 time);
+void SetTimetableParams(int param1, int param2, Ticks ticks);
 
 #endif /* TIMETABLE_H */

src/timetable_gui.cpp

@@ -39,14 +39,20 @@ enum TimetableViewWindowWidgets {
 	TTV_RESIZE,
 };
 
-void SetTimetableParams(int param1, int param2, uint32 time)
+/**
+ * Set the timetable parameters in the format as described by the setting.
+ * @param param1 the first DParam to fill
+ * @param param2 the second DParam to fill
+ * @param ticks  the number of ticks to 'draw'
+ */
+void SetTimetableParams(int param1, int param2, Ticks ticks)
 {
 	if (_settings_client.gui.timetable_in_ticks) {
 		SetDParam(param1, STR_TIMETABLE_TICKS);
-		SetDParam(param2, time);
+		SetDParam(param2, ticks);
 	} else {
 		SetDParam(param1, STR_TIMETABLE_DAYS);
-		SetDParam(param2, time / DAY_TICKS);
+		SetDParam(param2, ticks / DAY_TICKS);
 	}
 }