libs/js/jquery-mobile-1.2.0/node_modules/grunt/node_modules/prompt/node_modules/winston/node_modules/loggly/node_modules/timespan/README.md

   1 # timespan
   2
   3 A simple implementation of TimeSpans in Javascript.
   4
   5 ## Installation in node.js
   6
   7 ### Installing npm (node package manager)
   8 ``` bash
   9   $ curl http://npmjs.org/install.sh | sh
  10 ```
  11
  12 ### Installing timespan
  13 ``` bash
  14   [sudo] npm install timespan
  15 ```
  16
  17 ## Usage
  18 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.
  19
  20 ### Using the new constructor
  21
  22 ``` js
  23   var timespan = require('timespan');
  24   var ts = new timespan.TimeSpan();
  25 ```
  26
  27 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`.
  28
  29 ``` js
  30   //
  31   // Initializes the TimeSpan to 4 Minutes, 16 Seconds and 0 Milliseconds.
  32   //
  33   var ts = new TimeSpan(0,16,4)
  34
  35   //
  36   // Initializes the TimeSpan to 3 hours, 4 minutes, 10 seconds and 0 msecs.
  37   //
  38   var ts = new TimeSpan(0,10,64,2);
  39 ```
  40
  41 ### Using Construction Helper Method(s)
  42 You can initialize a new TimeSpan by calling one of these Functions:
  43
  44 ``` js
  45   timespan.FromSeconds(/* seconds */);
  46   timespan.FromMinutes(/* minutes */);
  47   timespan.FromHours(/* hours */);
  48   timespan.FromDays(/* hours */);
  49
  50   //
  51   // This behaves differently, see below
  52   //
  53   timespan.FromDates(start, end);
  54 ```
  55
  56 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.
  57
  58 `timespan.FromDates()` is different as it takes two dates. The TimeSpan will be the difference between these dates.
  59
  60 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.
  61
  62 ``` js
  63   var date1 = new Date(2010, 3, 1, 10, 10, 5, 0);
  64   var date2 = new Date(2010, 3, 1, 10, 10, 10, 0);
  65   var ts = TimeSpan.FromDates(date2, date1);
  66   var ts2 = TimeSpan.FromDates(date2, date1, true);
  67
  68   //
  69   // -5, because we put the later date first
  70   //
  71   console.log(ts.totalSeconds());
  72
  73   //
  74   // 5, because we passed true as third parameter
  75   //
  76   console.log(ts2.totalSeconds());
  77 ```
  78
  79
  80 ### Adding / Subtracting TimeSpans
  81 There are several functions to add or subtract time:
  82
  83 ``` js
  84   ts.addMilliseconds()
  85   ts.addSeconds()
  86   ts.addMinutes()
  87   ts.addHours()
  88   ts.addDays()
  89   ts.subtractMilliseconds()
  90   ts.subtractSeconds()
  91   ts.subtractMinutes()
  92   ts.subtractHours()
  93   ts.subtractDays()
  94 ```
  95
  96 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.
  97
  98 ``` js
  99   var ts = new TimeSpan();
 100   ts.addSeconds(30);
 101   ts.addMinutes(2);
 102   ts.subtractSeconds(60);
 103
 104   //
 105   // ts will now be a timespan of 1 minute and 30 seconds
 106   //
 107 ```
 108
 109 The parameter can be negative to negate the operation `ts.addSeconds(-30)` is equivalent to `ts.subtractSeconds(30)`.
 110
 111 ### Interacting with Other TimeSpan instances
 112 These are the functions that interact with another TimeSpan:
 113
 114 ``` js
 115   ts.add()
 116   ts.subtract()
 117   ts.equals()
 118 ```
 119
 120 add and subtract add/subtract the other TimeSpan to the current one:
 121
 122 ``` js
 123   var ts = TimeSpan.FromSeconds(30);
 124   var ts2 = TimeSpan.FromMinutes(2);
 125   ts.add(ts2);
 126
 127   //
 128   // ts is now a TimeSpan of 2 Minutes, 30 Seconds
 129   // ts2 is unchanged
 130   //
 131 ```
 132
 133 equals checks if two TimeSpans have the same time:
 134
 135 ``` js
 136   var ts = TimeSpan.FromSeconds(30);
 137   var ts2 = TimeSpan.FromSeconds(30);
 138   var eq = ts.equals(ts2); // true
 139   ts2.addSeconds(1);
 140   var eq2 = ts.equals(ts2); // false
 141 ```
 142
 143 ### Retrieving the Value of a TimeSpan
 144 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.
 145
 146 #### Retrieve the full value
 147
 148 ``` js
 149   ts.totalMilliseconds()
 150   ts.totalSeconds()
 151   ts.totalMinutes()
 152   ts.totalHours()
 153   ts.totalDays()
 154 ```
 155
 156 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.
 157
 158 ``` js
 159   var ts = TimeSpan.fromSeconds(90);
 160   console.log(ts.totalMilliseconds()); // 90000
 161   console.log(ts.totalSeconds());      // 90
 162   console.log(ts.totalMinutes());      // 1.5
 163   console.log(ts.totalMinutes(true));  // 1
 164 ```
 165
 166 #### Retrieve a component of the TimeSpan
 167
 168 ``` js
 169   ts.milliseconds
 170   ts.seconds
 171   ts.minutes
 172   ts.hours
 173   ts.days
 174 ```
 175
 176 These functions return a component of the TimeSpan that could be used to represent a clock.
 177
 178 ``` js
 179   var ts = TimeSpan.FromSeconds(90);
 180   console.log(ts.seconds()); // 30
 181   console.log(ts.minutes()); // 1
 182 ```
 183
 184 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:
 185
 186 ``` js
 187   var ts = TimeSpan.FromDays(2);
 188   ts.addHours(12);
 189   console.log(ts.days());  // 2
 190   console.log(ts.hours()); // 12
 191 ```
 192
 193 ## Remark about Backwards Compatibility
 194 Version 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`.
 195
 196 #### Author: [Michael Stum](http://www.stum.de)
 197 #### Contributors: [Charlie Robbins](http://github.com/indexzero)
 198
 199 [0]: http://nodejs.org