improved Date/DateTools specification

std/Date.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2005-2012 Haxe Foundation
+ * Copyright (C)2005-2013 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -19,62 +19,78 @@
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
  */
-/**
-	The Date class is used for date manipulation. There is some extra functions
-	available in the [DateTools] class.
-**/
 
+ /**
+	The Date class provides a basic structure for date and time related
+	information. Date instances can be created by
+		- new Date() for a specific date,
+		- Date.now() to obtain information about the current time,
+		- Date.fromTime() with a given timestamp or
+		- Date.fromString() by parsing from a String.
+	
+	There is some extra functions available in the [DateTools] class.
+	
+	In the context of haxe dates, a timestamp is defined as the number of
+	milliseconds elapsed since 1st January 1970.
+**/
 extern class Date
 {
 	/**
-		Creates a new date object.
+		Creates a new date object from the given arguments.
+		
+		The behaviour of a Date instance is only consistent across platforms if
+		the the arguments describe a valid date.
+			- month: 0 to 11
+			- day: 1 to 31
+			- hour: 0 to 23
+			- min: 0 to 59
+			- sec: 0 to 59
 	**/
 	function new(year : Int, month : Int, day : Int, hour : Int, min : Int, sec : Int ) : Void;
 
 	/**
-		Returns the timestamp of the date. It's the number of milliseconds
-		elapsed since 1st January 1970. It might only have a per-second precision
-		depending on the platforms.
+		Returns the timestamp of the date. It might only have a per-second
+		precision depending on the platforms.
 	**/
 	function getTime() : Float;
 
 	/**
-		Returns the hours value of the date (0-23 range).
+		Returns the hours of [this] Date (0-23 range).
 	**/
 	function getHours() : Int;
 
 	/**
-		Returns the minutes value of the date (0-59 range).
+		Returns the minutes of [this] Date (0-59 range).
 	**/
 	function getMinutes() : Int;
 
 	/**
-		Returns the seconds of the date (0-59 range).
+		Returns the seconds of the [this] Date (0-59 range).
 	**/
 	function getSeconds() : Int;
 
 	/**
-		Returns the full year of the date.
+		Returns the full year of [this] Date (4-digits).
 	**/
 	function getFullYear() : Int;
 
 	/**
-		Returns the month of the date (0-11 range).
+		Returns the month of [this] Date (0-11 range).
 	**/
 	function getMonth() : Int;
 
 	/**
-		Returns the day of the date (1-31 range).
+		Returns the day of [this] Date (1-31 range).
 	**/
 	function getDate() : Int;
 
 	/**
-		Returns the week day of the date (0-6 range).
+		Returns the day of the week of [this] Date (0-6 range).
 	**/
 	function getDay() : Int;
 
 	/**
-		Returns a string representation for the Date, by using the
+		Returns a string representation of [this] Date, by using the
 		standard format [YYYY-MM-DD HH:MM:SS]. See [DateTools.format] for
 		other formating rules.
 	**/
@@ -86,15 +102,18 @@ extern class Date
 	static function now() : Date;
 
 	/**
-		Returns a Date from a timestamp [t] which is the number of
-		milliseconds elapsed since 1st January 1970.
+		Returns a Date from timestamp [t].
 	**/
 	static function fromTime( t : Float ) : Date;
 
 	/**
-		Returns a Date from a formated string of one of the following formats :
-		[YYYY-MM-DD hh:mm:ss] or [YYYY-MM-DD] or [hh:mm:ss]. The first two formats
-		are expressed in local time, the third in UTC Epoch.
+		Returns a Date from a formated string [s], with the following accepted
+		formats:
+			- [YYYY-MM-DD hh:mm:ss]
+			- [YYYY-MM-DD]
+			- [hh:mm:ss]
+		The first two formats are expressed in local time, the third in UTC
+		Epoch.
 	**/
 	static function fromString( s : String ) : Date;
 

std/DateTools.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2005-2012 Haxe Foundation
+ * Copyright (C)2005-2013 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -19,11 +19,13 @@
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
  */
+
 /**
-	The DateTools class contains some extra functionalities for [Date]
-	manipulation. It's stored in a different class in order to prevent
-	the standard [Date] of being bloated and thus increasing the size of
-	each application using it.
+	The DateTools class contains some extra functionalities for handling [Date]
+	instances and timestamps.
+	
+	In the context of haxe dates, a timestamp is defined as the number of
+	milliseconds elapsed since 1st January 1970.
 **/
 class DateTools {
 
@@ -103,11 +105,11 @@ class DateTools {
 	#end
 
 	/**
-		Format the date [d] according to the format [f]. The format
-		is compatible with the [strftime] standard format, except that there
-		is no support in Flash and JS for day and months names (due to lack
-		of proper internationalization API). On haXe/Neko/Windows, some
-		formats are not supported.
+		Format the date [d] according to the format [f]. The format is
+		compatible with the [strftime] standard format, except that there is no
+		support in Flash and JS for day and months names (due to lack of proper
+		internationalization API). On haXe/Neko/Windows, some formats are not
+		supported.
 	**/
 	public static function format( d : Date, f : String ) : String {
 		#if (neko && !(macro || interp))
@@ -120,16 +122,21 @@ class DateTools {
 	}
 
 	/**
-		Returns a Date which time has been changed by [t] milliseconds.
+		Returns the result of adding timestamp [t] to Date [d].
+		
+		This is a convenience function for calling
+		Date.fromTime(d.getTime() + t).
 	**/
-	public static function delta( d : Date, t : Float ) : Date {
+	public static inline function delta( d : Date, t : Float ) : Date {
 		return Date.fromTime( d.getTime() + t );
 	}
 
 	static var DAYS_OF_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 
 	/**
-		Returns the number of days in a month
+		Returns the number of days in the month of Date [d].
+		
+		This method handles leap years.
 	**/
 	public static function getMonthDays( d : Date ) : Int {
 		var month = d.getMonth();
@@ -143,30 +150,30 @@ class DateTools {
 	}
 
 	/**
-		Convert a number of seconds to a date-time
+		Converts a number of seconds to a timestamp.
 	**/
-	public static function seconds( n : Float ) : Float {
+	public static inline function seconds( n : Float ) : Float {
 		return n * 1000.0;
 	}
 
 	/**
-		Convert a number of minutes to a date-time
+		Converts a number of minutes to a timestamp.
 	**/
-	public static function minutes( n : Float ) : Float {
+	public static inline function minutes( n : Float ) : Float {
 		return n * 60.0 * 1000.0;
 	}
 
 	/**
-		Convert a number of hours to a date-time
+		Converts a number of hours to a timestamp.
 	**/
-	public static function hours( n : Float ) : Float {
+	public static inline function hours( n : Float ) : Float {
 		return n * 60.0 * 60.0 * 1000.0;
 	}
 
 	/**
-		Convert a number of days to a date-time
+		Converts a number of days to a timestamp.
 	**/
-	public static function days( n : Float ) : Float {
+	public static inline function days( n : Float ) : Float {
 		return n * 24.0 * 60.0 * 60.0 * 1000.0;
 	}
 

tests/unit/unitstd/Date.unit.hx

@@ -0,0 +1,11 @@
+// we only specify basic things here, most invalid input is platform-dependent
+var date = new Date(1982,10,10,14,2,20);
+date.getHours() == 14;
+date.getMinutes() == 2;
+date.getSeconds() == 20;
+date.getFullYear() == 1982;
+date.getMonth() == 10;
+date.getDate() == 10;
+date.getDay() == 3;
+date.getTime() == 405781340000.;
+date.toString() == "1982-11-10 14:02:20";

tests/unit/unitstd/DateTools.unit.hx

@@ -0,0 +1,8 @@
+// leap year
+var d = new Date(2012, 01, 17, 01, 02, 03);
+DateTools.getMonthDays(d) == 29;
+
+// seconds/delta
+var diff = DateTools.seconds(59);
+var d2 = DateTools.delta(d, diff);
+d2.toString() == "2012-02-17 01:03:02";