{"dist":{"shasum":"4902ce040bd13d845c8f59b27e9d59bad6f39929","tarball":"https://registry.npmjs.org/timespan/-/timespan-2.3.0.tgz","integrity":"sha512-0Jq9+58T2wbOyLth0EU+AUb6JMGCLaTWIykJFa7hyAybjVH9gpVMTfUAwo5fWAvtFt2Tjh/Elg8JtgNpnMnM8g==","signatures":[{"sig":"MEQCIGYS91aNymuLnF2O02cvwkFWQN5xtyZJx/ax5iwP9DooAiAoEcHUW92OsdEcVfsqbhmPoHewzmkTLZHGgh30cDe7lw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"./lib/time-span.js","name":"timespan","_from":".","author":{"name":"Michael Stum","email":"blog@stum.de"},"readme":"# timespan\n\nA simple implementation of TimeSpans in Javascript.\n\n## Installation in node.js\n\n### Installing npm (node package manager)\n``` bash\n  $ curl http://npmjs.org/install.sh | sh\n```\n\n### Installing timespan\n``` bash\n  [sudo] npm install timespan\n```\n\n## Usage \nYou 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.\n\n### Using the new constructor\n\n``` js\n  var timespan = require('timespan');\n  var ts = new timespan.TimeSpan();\n```\n\nThe 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`.\n\n``` js\n  //\n  // Initializes the TimeSpan to 4 Minutes, 16 Seconds and 0 Milliseconds.\n  //\n  var ts = new TimeSpan(0,16,4)\n\n  //\n  // Initializes the TimeSpan to 3 hours, 4 minutes, 10 seconds and 0 msecs.\n  //\n  var ts = new TimeSpan(0,10,64,2);\n```\n\n### Using Construction Helper Method(s) \nYou can initialize a new TimeSpan by calling one of these Functions:\n\n``` js\n  timespan.FromSeconds(/* seconds */);\n  timespan.FromMinutes(/* minutes */);\n  timespan.FromHours(/* hours */);\n  timespan.FromDays(/* hours */);\n    \n  //\n  // This behaves differently, see below\n  //\n  timespan.FromDates(start, end);\n```\n\nThe 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.\n\n`timespan.FromDates()` is different as it takes two dates. The TimeSpan will be the difference between these dates.\n\nIf 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.\n\n``` js\n  var date1 = new Date(2010, 3, 1, 10, 10, 5, 0);\n  var date2 = new Date(2010, 3, 1, 10, 10, 10, 0);\n  var ts = TimeSpan.FromDates(date2, date1);\n  var ts2 = TimeSpan.FromDates(date2, date1, true);\n  \n  //\n  // -5, because we put the later date first\n  //\n  console.log(ts.totalSeconds()); \n  \n  //\n  // 5, because we passed true as third parameter\n  //\n  console.log(ts2.totalSeconds()); \n```\n\n\n### Adding / Subtracting TimeSpans\nThere are several functions to add or subtract time:\n\n``` js\n  ts.addMilliseconds()\n  ts.addSeconds()\n  ts.addMinutes()\n  ts.addHours()\n  ts.addDays()\n  ts.subtractMilliseconds()\n  ts.subtractSeconds()\n  ts.subtractMinutes()\n  ts.subtractHours()\n  ts.subtractDays()\n```\n\nAll 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.\n\n``` js\n  var ts = new TimeSpan();\n  ts.addSeconds(30);\n  ts.addMinutes(2);\n  ts.subtractSeconds(60);\n  \n  //\n  // ts will now be a timespan of 1 minute and 30 seconds\n  //\n```\n\nThe parameter can be negative to negate the operation `ts.addSeconds(-30)` is equivalent to `ts.subtractSeconds(30)`.\n\n### Interacting with Other TimeSpan instances\nThese are the functions that interact with another TimeSpan:\n\n``` js\n  ts.add()\n  ts.subtract()\n  ts.equals()\n```\n\nadd and subtract add/subtract the other TimeSpan to the current one:\n\n``` js\n  var ts = TimeSpan.FromSeconds(30);\n  var ts2 = TimeSpan.FromMinutes(2);\n  ts.add(ts2);\n  \n  //\n  // ts is now a TimeSpan of 2 Minutes, 30 Seconds\n  // ts2 is unchanged\n  //\n```\n\nequals checks if two TimeSpans have the same time:\n\n``` js\n  var ts = TimeSpan.FromSeconds(30);\n  var ts2 = TimeSpan.FromSeconds(30);\n  var eq = ts.equals(ts2); // true\n  ts2.addSeconds(1);\n  var eq2 = ts.equals(ts2); // false\n```\n\n### Retrieving the Value of a TimeSpan\nThere 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.\n\n#### Retrieve the full value\n\n``` js\n  ts.totalMilliseconds()\n  ts.totalSeconds()\n  ts.totalMinutes()\n  ts.totalHours()\n  ts.totalDays()\n```\n\nThese 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.\n\n``` js\n  var ts = TimeSpan.fromSeconds(90);\n  console.log(ts.totalMilliseconds()); // 90000\n  console.log(ts.totalSeconds());      // 90\n  console.log(ts.totalMinutes());      // 1.5\n  console.log(ts.totalMinutes(true));  // 1\n```\n\n#### Retrieve a component of the TimeSpan\n\n``` js\n  ts.milliseconds\n  ts.seconds\n  ts.minutes\n  ts.hours\n  ts.days\n```\n\nThese functions return a component of the TimeSpan that could be used to represent a clock. \n\n``` js\n  var ts = TimeSpan.FromSeconds(90);\n  console.log(ts.seconds()); // 30\n  console.log(ts.minutes()); // 1\n```\n\nBasically 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:\n\n``` js\n  var ts = TimeSpan.FromDays(2);\n  ts.addHours(12);\n  console.log(ts.days());  // 2\n  console.log(ts.hours()); // 12\n```\n\n## Remark about Backwards Compatibility\nVersion 0.2.x was designed to work with [node.js][0] 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`.\n\n#### Author: [Michael Stum](http://www.stum.de)\n#### Contributors: [Charlie Robbins](http://github.com/indexzero)\n\n[0]: http://nodejs.org ","engines":{"node":">= 0.2.0"},"scripts":{"test":"vows test/*-test.js --spec"},"_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"keywords":["time","dates","utilities","timespan"],"repository":{"url":"https://github.com/indexzero/TimeSpan.js.git","type":"git"},"_npmVersion":"1.2.14","description":"A JavaScript TimeSpan library for node.js (and soon the browser)","maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"contributors":[{"name":"Charlie Robbins","email":"charlie.robbins@gmail.com"}],"readmeFilename":"README.md","devDependencies":{"vows":">= 0.7.0"},"_id":"timespan@2.3.0","version":"2.3.0"}