Suppose you are building an application that displays all the timetables of buses and trains in your area. The user can select a journey, and you want to be able to tell him how long his trip will take. To do so, you will have to take the arrival time and subtract it from the departure time.
Simply using the written expression of hours won’t be effective : how will you manage to calculate the journey of a night train leaving at 8pm and arriving at 7:58am the next morning? How will you handle the Orient-Express that leaves at 20h50 from Nice and arrives in Moscow nearly two days later ?
You have to have a unique representation of these two specific points in time, and this is where the Date Object comes in.
January 1st, 1970 is when it all began
- When reflecting the date and time from a browser you are completely bound to the user’s computer day and time: if the user did not set the date right on his computer, your Date object will reflect these false settings.
- Whilst you can read the system date and time set on the user’s computer, and set your own changes inside your Date object according to the date your read from the computer, you cannot change the computer’s system date and time: the user’s system date and time will always remain unchanged.
While working on your own instance of the Date object representing a specific date, a number of methods allow you to operate on it. Most methods simply allow you to get and set the year, month, day, hour, minute, second, and millisecond fields of the object. But in this article we will focus only on the creation phase of the Date object.
How to construct Date objects ?
The syntax for creating your Date() object is as follows:
var myDate = new Date(optional parameters);
Good to know
Fri Sep 02 2016 17:24:56 GMT+0200 (CEST)
Let’s discuss here how you can implement these two methods.
I. Passing parameters to an instance of a Date Object
1/ Passing no arguments at all, which will generate the current date, to the millisecond
var today = new Date();
// Prints Sun Jun 18 2017 17:24:56 GMT+0200 (CEST)
If no arguments are provided, it creates an object for the current date and time. Passing no argument will display the current date as interpreted by my browser given the settings of my computer.
2/ Passing a number corresponding to the number of milliseconds since Epoch time
var milliseconds = new Date(5000);
// Prints Thu Jan 01 1970 01:00:05 GMT+0100 (CET)
Passing the argument 5000 will create a date that represents five seconds past midnight on January 1st, 1970.
3/ Passing a string with a very specific format that will be interpreted as a date
var dateAsString = new Date(dateString);
ISO date (the international standard), written as : “2016–09–02”.
→ Complete date (YYYY-MM-DD)
var dateISO = new Date(“2016–03–25”);
// Prints Fri Mar 25 2016 01:00:00 GMT+0100 (CET)
→ Year and month (YYYY-MM)
var dateISO = new Date("2016-03");
// Prints Tue Mar 01 2016 01:00:00 GMT+0100 (CET)
→ Year (YYYY)
var dateISO = new Date("2016");
// Prints Fri Jan 01 2016 01:00:00 GMT+0100 (CET)
→ With added hours, minutes and seconds (YYYY-MM-DDTHH:MM:SS)
var dateISO = new Date("2016-03-25T12:00:00");
// Prints Fri Mar 25 2016 13:00:00 GMT+0100 (CET)
Short dates, written as : “03/25/2015” or “2015/03/25”
Short dates are more often passed to the Date object with the “MM/DD/YYYY” syntax, but can also be written as “YYYY/MM/DD”.
→ “MM/DD/YYYY” format
var dateShort = new Date("03/25/2016");
// Prints Fri Mar 25 2016 00:00:00 GMT+0100 (CET)
→ “YYYY/MM/DD” format
var dateShort = new Date("2016/03/25");
// Prints Fri Mar 25 2016 00:00:00 GMT+0100 (CET)
Good to know
- Month is written before day in all short date and ISO date formats.
- If you write month and day numbers without a leading zero (2 instead of 02 for example), they will still be interpreted and output the right date)
Long dates, written as : “Mar 25 2016” or “25 March 2016”.
The most used syntax for long dates string format is “Day Month Year”. However, day, month and year names can be written in any order.
Month names can be written in full (March) or abbreviated (Mar) and are case insensitive.
One more thing to take note of: if you add commas or any kind of separator inside the string, they will be ignored.
var date1 = new Date("3 march 2016");
var date2 = new Date("3 MARCH, 2016");
var date3 = new Date("2016 3 March");
var date4 = new Date("3 2016 mar");
var date5 = new Date("March 2016 3");
var date6 = new Date("March*2016,3");
// All of the above will print Thu Mar 03 2016 00:00:00 GMT+0100 (CET)
Full date, written as : “Thursday March 03 2016”.
var dateFull = new Date("Mon Mar 02 2015 00:00:00 GMT+0100 (CET)");
// Prints Mon Mar 02 2015 00:00:00 GMT+0100 (CET)
Timezone-related parenthesis like (CET) in our example are optional and will be ignored if erroneous.
Good to know
String parameters and Timezones: be aware
When you pass a string representing a date for example, if no timezone is specified, this date will be converted to match the timezone you are in.
In other words: If a date/time is created in GMT (Greenwich Mean Time), the date/time will be converted to CDT (Central US Daylight Time) if a user browses from central US.
Thus, when you pass for example :
var newYear = new Date(“2016”);
Depending on the timezone your are in, the output could vary between December 31 2015 and January 01 2016.
String parameters are converted to numbers by the Date object
When a string is passed as a parameter to the Date object, it is then converted into a number (number of milliseconds since Epoch Time).
If the string format is illegal and not accepted by the Date object, the parameter will be passed as “NaN” (Not a Number) and result in an “Invalid date” error.
4/ Passing every argument in the right order, separated by a comma
var d = new Date(year, month, day [,hour,minute,second,millisecond ]);
The last four arguments (hour, minute, second, millisecond) are optional and taken to 0 if not specified. When one of these four optional arguments is specified, all the other arguments to its left must also be specified.
→ Be careful : If you give the Date object a single argument, that argument will be treated as a millisecond count, not as the first parameter (year).
Let’s review these arguments one by one and see how they can be used as parameters of a Date object:
Specify the year in full (use 1998 instead of 98 for example). However, be aware that if you use a two-digit date between 0 and 99, 1900 will be added to the integer (98 will become 1998).
The month parameter is zero-based (contrary to the day parameter). The integer will therefore be comprised between 0 (January) and 11 (December)
The day parameter represents the day of the month. It begins at 1 (contrary to the month parameter) and the integer will be comprised between 1 and 31.
The hour parameter represents the hour of the day on a 24 hours scale. The integer will be comprised between 0 and 23.
The minute parameter is on a 60 minutes scale. The integer will be comprised between 0 and 59.
The second parameter is on a 60 seconds scale. The integer will be comprised between 0 and 59.
The millisecond parameter is on a 1000 milliseconds scale. The integer will be comprised between 0 and 999.
var theDate = new Date(2016,6,17,21,15,30,0);
// Prints Sun Jul 17 2016 21:15:30 GMT+0200 (CEST)
Note that the month number (6) corresponds to July and not June, due to the zero-based structure of the month parameter.
II. Using the “set” methods that set a component’s value within a Date
The Date object’s methods, that can be used on an instance of date, feature
set methods for setting specific components of the date.
These methods let you set values for a part of the date : years, months, days, hours, minutes, seconds and milliseconds.
Let’s create for example an instance of the Date object that will represent the current date, and review the set methods we can apply to this newly created
myDate variable :
var myDate = new Date();
// Prints Sat Sep 03 2016 16:22:20 GMT+0200 (CEST)
Sets the year (optionally month and day)
// Prints Mon Sep 03 2001 16:28:40 GMT+0200 (CEST)
Sets the month (0–11)
// Prints Thu Mar 03 2016 16:33:48 GMT+0100 (CET)
Sets the day of the month as a number (1–31)
// Prints Sun Sep 25 2016 16:22:20 GMT+0200 (CEST)
Sets the hour (0–23)
// Prints Sat Sep 03 2016 09:31:23 GMT+0200 (CEST)
Sets the minutes (0–59)
// Prints Sat Sep 03 2016 16:01:02 GMT+0200 (CEST)
Sets the seconds (0–59)
// Prints Sat Sep 03 2016 16:36:30 GMT+0200 (CEST)
Sets the milliseconds (0–999)
Sets the time in milliseconds since January 1, 1970
What can be puzzling when manipulating dates is the management of the different timezones users find themselves in, along with the lack of control on the user’s computer settings.
Feel free to comment and like this article so that others can find it easily on Medium !