timespan
A simple implementation of TimeSpans in Javascript.
Installation in node.js
Installing npm (node package manager)
$ curl http://npmjs.org/install.sh | sh
Installing timespan
[sudo] npm install timespan
Usage
You have two options when creating a new TimeSpan object: either explicitly instantiate it using the TimeSpan constructor function or use a helper method to create from a specific length of time.
Using the new constructor
var timespan = require('timespan');
var ts = new timespan.TimeSpan();
The constructor takes 5 parameters, all which are optional and which can be used to initialize the TimeSpan to a given value. These parameters are: milliseconds, seconds, minutes, hours, days.
//
// Initializes the TimeSpan to 4 Minutes, 16 Seconds and 0 Milliseconds.
//
var ts = new TimeSpan(0,16,4)
//
// Initializes the TimeSpan to 3 hours, 4 minutes, 10 seconds and 0 msecs.
//
var ts = new TimeSpan(0,10,64,2);
Using Construction Helper Method(s)
You can initialize a new TimeSpan by calling one of these Functions:
timespan.FromSeconds(/* seconds */);
timespan.FromMinutes(/* minutes */);
timespan.FromHours(/* hours */);
timespan.FromDays(/* hours */);
//
// This behaves differently, see below
//
timespan.FromDates(start, end);
The first four helper methods take a single numeric parameter and create a new TimeSpan instance. e.g. timespan.FromSeconds(45) is equivalent to new TimeSpan(0,45). If the parameter is invalid/not a number, it will just be treated as 0 no error will be thrown.
timespan.FromDates() is different as it takes two dates. The TimeSpan will be the difference between these dates.
If the second date is earlier than the first date, the TimeSpan will have a negative value. You can pass in "true" as the third parameter to force the TimeSpan to be positive always.
var date1 = new Date(2010, 3, 1, 10, 10, 5, 0);
var date2 = new Date(2010, 3, 1, 10, 10, 10, 0);
var ts = TimeSpan.FromDates(date2, date1);
var ts2 = TimeSpan.FromDates(date2, date1, true);
//
// -5, because we put the later date first
//
console.log(ts.totalSeconds());
//
// 5, because we passed true as third parameter
//
console.log(ts2.totalSeconds());
Adding / Subtracting TimeSpans
There are several functions to add or subtract time:
ts.addMilliseconds()
ts.addSeconds()
ts.addMinutes()
ts.addHours()
ts.addDays()
ts.subtractMilliseconds()
ts.subtractSeconds()
ts.subtractMinutes()
ts.subtractHours()
ts.subtractDays()
All these functions take a single numeric parameter. If the parameter is invalid, not a number, or missing it will be ignored and no Error is thrown.
var ts = new TimeSpan();
ts.addSeconds(30);
ts.addMinutes(2);
ts.subtractSeconds(60);
//
// ts will now be a timespan of 1 minute and 30 seconds
//
The parameter can be negative to negate the operation ts.addSeconds(-30) is equivalent to ts.subtractSeconds(30).
Interacting with Other TimeSpan instances
These are the functions that interact with another TimeSpan:
ts.add()
ts.subtract()
ts.equals()
add and subtract add/subtract the other TimeSpan to the current one:
var ts = TimeSpan.FromSeconds(30);
var ts2 = TimeSpan.FromMinutes(2);
ts.add(ts2);
//
// ts is now a TimeSpan of 2 Minutes, 30 Seconds
// ts2 is unchanged
//
equals checks if two TimeSpans have the same time:
var ts = TimeSpan.FromSeconds(30);
var ts2 = TimeSpan.FromSeconds(30);
var eq = ts.equals(ts2); // true
ts2.addSeconds(1);
var eq2 = ts.equals(ts2); // false
Retrieving the Value of a TimeSpan
There are two sets of functions to retreive the function of the TimeSpan: those that deal with the full value in various measurements and another that gets the individual components.
Retrieve the full value
ts.totalMilliseconds()
ts.totalSeconds()
ts.totalMinutes()
ts.totalHours()
ts.totalDays()
These functions convert the value to the given format and return it. The result can be a floating point number. These functions take a single parameter roundDown which can be set to true to round the value down to an Integer.
var ts = TimeSpan.fromSeconds(90);
console.log(ts.totalMilliseconds()); // 90000
console.log(ts.totalSeconds()); // 90
console.log(ts.totalMinutes()); // 1.5
console.log(ts.totalMinutes(true)); // 1
Retrieve a component of the TimeSpan
ts.milliseconds
ts.seconds
ts.minutes
ts.hours
ts.days
These functions return a component of the TimeSpan that could be used to represent a clock.
var ts = TimeSpan.FromSeconds(90);
console.log(ts.seconds()); // 30
console.log(ts.minutes()); // 1
Basically these value never "overflow" - seconds will only return 0 to 59, hours only 0 to 23 etc. Days could grow infinitely. All of these functions automatically round down the result:
var ts = TimeSpan.FromDays(2);
ts.addHours(12);
console.log(ts.days()); // 2
console.log(ts.hours()); // 12
Remark about Backwards Compatibility
Version 0.2.x was designed to work with node.js and backwards compatibility to the browser-based usage was not considered a high priority. This will be fixed in future versions, but for now if you need to use this in the browser, you can find the 0.1.x code under /browser.