<a href="http://github.com/timrwood/underscore.date">underscore.date</a>
<span class="small">by <a href="http://github.com/timrwood">timrwood</a></span>
</h1>
+ <p>Underscore.date is a javascript date library that helps create, manipulate, and format dates
+ without extending the Date prototype.</p>
- <p>Underscore.date is a javascript date library that helps create, manipulate, and format dates without extending the Date prototype.</p>
-
- <p>Author: Tim Wood (washwithcare@gmail.com)</p>
- <p>Version: 0.5.2</p>
- <p class="filesize">1.82 kb (min + gzip)</p>
-
- <h2>Download</h2>
- <p>You can download this project in either
- <a href="http://github.com/timrwood/underscore.date/zipball/master">zip</a> or
- <a href="http://github.com/timrwood/underscore.date/tarball/master">tar</a> formats.
- </p>
- <p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:
- <pre>$ git clone git://github.com/timrwood/underscore.date</pre>
- </p>
+ <div class="col-1">
+ <h2>2.02 kb (min + gzip)</h2>
+ <p>Version 0.6.0</p>
+ <p>Author: Tim Wood</p>
+ </div>
+ <div class="col-1">
+ <h2>Download</h2>
+ <p>You can download this project in either
+ <a href="http://github.com/timrwood/underscore.date/zipball/master">zip</a> or
+ <a href="http://github.com/timrwood/underscore.date/tarball/master">tar</a> formats.
+ </p>
+ <p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:
+ <pre>$ git clone git://github.com/timrwood/underscore.date</pre>
+ </p>
+ </div>
+ <div class="clearfix"></div>
- <h1>Where to use it</h1>
- <h3>Node.js</h3>
+ <h1>Works in the browser and in Node.js!</h1>
- <p>Install with npm</p>
+ <h3>Node.js</h3>
<pre><code>npm install underscore.date</code></pre>
- <p>Usage</p>
-
<pre><code>var _date = require('underscore.date');
console.log(_date('September 9 1999').fromNow());</code></pre>
<pre><code>_date('September 9 1999').fromNow();</code></pre>
- <h2>_date() </h2>
-
- <p>The library works by creating a <code>_date()</code> wrapper object. To create that wrapper, you can pass any of the following data types in.</p>
-
- <h3>Number</h3>
-
- <pre><code>_date(1300291340510)</code></pre>
-
- <p>An integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.</p>
-
- <h3>Date</h3>
-
- <pre><code>_date(new Date(2010, 1, 14, 15, 25, 50, 125))</code></pre>
-
- <p>Any valid <code>Date</code> object. For more information on <code>Date</code> objects, see <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date">the JavaScript Date documentation at MDN</a></p>
-
- <h3>Array</h3>
-
- <pre><code>_date([2010, 1, 14, 15, 25, 50, 125])</code></pre>
- <p>An array mirroring the parameters passed into <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/UTC">Date.UTC()</a>.</p>
- <p><code>[year, month = 0, date = 1, hours = 0, minutes = 0, seconds = 0, milliseconds = 0]</code></p>
+ <h2>Examples</h2>
- <p>Any value past the year is optional, and will default to the lowest possible number.</p>
+ <p>Format a Unix timestamp</p>
- <h3>undefined</h3>
+ <pre><code>_date(1300291340510).format("MMMM Do, YYYY") // >>> "March 16th, 2011" </code></pre>
- <pre><code>_date()</code></pre>
+ <p>Get timeago for a date string</p>
- <p>If no value is passed to a 'dateInput' parameter, it will default to the current time using <code>new Date()</code>.</p>
+ <pre><code>_date("7-10-1986", "MM-DD-YYYY").fromNow() // >>> "25 years ago" </code></pre>
- <pre><code>_date() === _date(new Date())</code></pre>
+ <p>Get the current time and add 3 hours</p>
- <h3>String</h3>
+ <pre><code>_date().add({h:3}).fromNow() // >>> "in 3 hours" </code></pre>
- <pre><code>_date("Dec 25, 1995")</code></pre>
-
- <p>A string that can be parsed by <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/parse">Date.parse()</a>.</p>
-
- <h3>String with format</h3>
-
- <pre><code>_date("12-25-1995", "MM-DD-YYYY")</code></pre>
-
- <p>A string and a format string. The second string will be used as the format to parse the first string.</p>
-
- <p>The format parts are similar to the formats from _date().format()</p>
-
- <p><strong>Important:</strong> Parsing a string with a format is by far the slowest method of creating a date.
- If you have the ability to change the input, it is much faster (~15x) to use Unix timestamps.</p>
-
- <table>
- <tbody><tr>
- <th>Input</th>
- <th>Output</th>
- </tr>
- <tr>
- <td>M or MM</td>
- <td>Month</td>
- </tr>
- <tr>
- <td>D or DD</td>
- <td>Day of month</td>
- </tr>
- <tr>
- <td>DDD or DDDD</td>
- <td>Day of year</td>
- </tr>
- <tr>
- <td>YY</td>
- <td>2 digit year (if greater than 70, will return 1900's, else 2000's)</td>
- </tr>
- <tr>
- <td>YYYY</td>
- <td>4 digit year</td>
- </tr>
- <tr>
- <td>a or A</td>
- <td>AM/PM</td>
- </tr>
- <tr>
- <td>H, HH, h, or hh</td>
- <td>24 hour (for 12 hour time, use in conjunction with a or A)</td>
- </tr>
- <tr>
- <td>m or mm</td>
- <td>Minutes</td>
- </tr>
- <tr>
- <td>s or ss</td>
- <td>Seconds</td>
- </tr>
- </tbody></table>
+ <p>Change the language</p>
- <h1>_date Prototype</h1>
-
- <p><code>underscore.date</code> contains a number of utility functions for manipulating and formatting dates.</p>
-
- <h2>_date.add()</h2>
-
- <pre><code>_date.add(object)</code></pre>
-
- <p>Adds time per the object passed in.</p>
-
- <p>The object should have key value pairs as shown below.</p>
-
- <pre><code>{
- ms : 200, // milliseconds
- s : 10, // seconds
- m : 10, // minutes (note: lowercase)
- h : 2, // hours
- d : 3, // days
- M : 2, // months (note: uppercase)
- y : 3 // years
-}</code></pre>
-
- <p>All the parameters are optional. Also, there are no upper limits for the values, so you can overload any of the parameters.</p>
-
- <pre><code>{ ms : 1000000 } // a million milliseconds
-{ d : 360 } // 360 days</code></pre>
+ <pre><code>_date(1300291340510).format("MMMM Do, YYYY") // >>> "March 16th, 2011"
+_date.lang('pt');
+_date(1300291340510).format("MMMM Do, YYYY") // >>> "Março 16o, 2011"
+_date.lang('en');
+_date(1300291340510).format("MMMM Do, YYYY") // >>> "March 16th, 2011"</code></pre>
- <h3>Special considerations for months and years</h3>
- <p>If the day of the month on the original date is greater than the number of days in the final month, the day of the month will change to the last day in the final month.</p>
-
- <p>Example:</p>
-
- <pre><code>_date([2010, 0, 31]) // January 31
-_date([2010, 0, 31]).add({M : 1}) // February 28</code></pre>
-
- <h2>_date.subtract()</h2>
-
- <pre><code>_date.subtract(object)</code></pre>
-
- <p>Functions the same as <code>_date.add()</code>, only using subtraction instead of addition.</p>
-
- <p>Example:</p>
-
- <pre><code>_date([2010, 1, 28]) // February 28
-_date([2010, 1, 28]).subtract({M:1}) // January 28</code></pre>
-
- <h2>_date.format()</h2>
-
- <pre><code>_date.format(string)</code></pre>
-
- <p>Returns a human readable string based on the format string that was passed in.</p>
-
- <pre><code>var dateToFormat = new Date(2010, 1, 14, 15, 25, 50, 125);
-_date(dateToFormat).format("dddd, MMMM Do YYYY, h:mm:ss a");
- // "Sunday, February 14th 2010, 3:25:50 pm"
-_date(dateToFormat).format("ddd, hA");
- // "Sun, 3PM"</code></pre>
-
- <p>The formats are created by creating a string of replacable characters.</p>
-
- <table>
- <tbody><tr>
- <th>Input</th>
- <th>Output</th>
- </tr>
- <tr>
- <td><b>Month</b></td>
- <td></td>
- </tr>
- <tr>
- <td>M</td>
- <td>1 2 ... 11 12</td>
- </tr>
- <tr>
- <td>Mo</td>
- <td>1st 2nd ... 11th 12th</td>
- </tr>
- <tr>
- <td>MM</td>
- <td>01 02 ... 11 12</td>
- </tr>
- <tr>
- <td>MMM</td>
- <td>Jan Feb ... Nov Dec</td>
- </tr>
- <tr>
- <td>MMMM</td>
- <td>January February ... November December</td>
- </tr>
- <tr>
- <td><b>Day of Month</b></td>
- <td></td>
- </tr>
- <tr>
- <td>D</td>
- <td>1 2 ... 30 30</td>
- </tr>
- <tr>
- <td>Do</td>
- <td>1st 2nd ... 30th 31st</td>
- </tr>
- <tr>
- <td>DD</td>
- <td>01 02 ... 30 31</td>
- </tr>
- <tr>
- <td><b>Day of Year</b></td>
- <td></td>
- </tr>
- <tr>
- <td>DDD</td>
- <td>1 2 ... 364 365</td>
- </tr>
- <tr>
- <td>DDDo</td>
- <td>1st 2nd ... 364th 365th</td>
- </tr>
- <tr>
- <td>DDDD</td>
- <td>001 002 ... 364 365</td>
- </tr>
- <tr>
- <td><b>Day of Week</b></td>
- <td></td>
- </tr>
- <tr>
- <td>d</td>
- <td>0 1 ... 5 6</td>
- </tr>
- <tr>
- <td>do</td>
- <td>0th 1st ... 5th 6th</td>
- </tr>
- <tr>
- <td>ddd</td>
- <td>Sun Mon ... Fri Sat</td>
- </tr>
- <tr>
- <td>dddd</td>
- <td>Sunday Monday ... Friday Saturday</td>
- </tr>
- <tr>
- <td><b>Week of Year</b></td>
- <td></td>
- </tr>
- <tr>
- <td>w</td>
- <td>1 2 ... 52 53</td>
- </tr>
- <tr>
- <td>wo</td>
- <td>1st 2nd ... 52nd 53rd</td>
- </tr>
- <tr>
- <td>ww</td>
- <td>01 02 ... 52 53</td>
- </tr>
- <tr>
- <td><b>Year</b></td>
- <td></td>
- </tr>
- <tr>
- <td>YY</td>
- <td>70 71 ... 29 30</td>
- </tr>
- <tr>
- <td>YYYY</td>
- <td>1970 1971 ... 2029 2030</td>
- </tr>
- <tr>
- <td><b>AM/PM</b></td>
- <td></td>
- </tr>
- <tr>
- <td>A</td>
- <td>AM PM</td>
- </tr>
- <tr>
- <td>a</td>
- <td>am pm</td>
- </tr>
- <tr>
- <td><b>Hour</b></td>
- <td></td>
- </tr>
- <tr>
- <td>H</td>
- <td>0 1 ... 22 23</td>
- </tr>
- <tr>
- <td>HH</td>
- <td>00 01 ... 22 23</td>
- </tr>
- <tr>
- <td>h</td>
- <td>1 2 ... 11 12</td>
- </tr>
- <tr>
- <td>hh</td>
- <td>01 02 ... 11 12</td>
- </tr>
- <tr>
- <td><b>Minute</b></td>
- <td></td>
- </tr>
- <tr>
- <td>m</td>
- <td>0 1 ... 58 59</td>
- </tr>
- <tr>
- <td>mm</td>
- <td>00 01 ... 58 59</td>
- </tr>
- <tr>
- <td><b>Second</b></td>
- <td></td>
- </tr>
- <tr>
- <td>s</td>
- <td>0 1 ... 58 59</td>
- </tr>
- <tr>
- <td>ss</td>
- <td>00 01 ... 58 59</td>
- </tr>
- <tr>
- <td><b>Timezone</b></td>
- <td></td>
- </tr>
- <tr>
- <td>z</td>
- <td>EST CST ... MST PST</td>
- </tr>
- <tr>
- <td>zz</td>
- <td>
- Eastern Standard Time ... Pacific Standard Time<br><br>
- NOTE: Internet Explorer uses a different implementation of
- Date.toString(), so we are unable to retrieve the full string
- of the timezone, and will fall back to 'z'.<br><br>
- So:<br>
- Firefox, Chrome, Safari, etc. == 'Eastern Standard Time'<br>
- Internet Explorer, etc. == 'EST'
-
- </td>
- </tr>
- </tbody></table><h2>_date.from()</h2>
-
- <pre><code>_date.from(date, withoutSuffix:boolean, asMilliseconds:boolean)</code></pre>
-
- <p>Returns a string as relative time ('minutes ago', '5 months ago', etc).</p>
-
- <p>You can pass anything that you would pass to _date() as the first parameter, or a <code>_date()</code> object.</p>
-
- <pre><code>_date([2007, 0, 29]).from(_date([2007, 0, 28])) // "a day ago"</code></pre>
-
- <p>You can pass <code>true</code> as the second parameter to return without the prefixes and suffixes.</p>
-
- <pre><code>_date([2007, 0, 29]).from(_date([2007, 0, 28]), true) // "a day"</code></pre>
-
- <p>You can pass <code>true</code> as the third parameter to return as milliseconds.
- The number of milliseconds returned will be positive if the date passed
- in is later than the first date, and negative if the date passed in is earlier.</p>
-
- <pre><code>_date([2007, 0, 29]).from(_date([2007, 0, 28]), true , true) // -86400000);
-_date([2007, 0, 27]).from(_date([2007, 0, 28]), true , true) // 86400000);</code></pre>
-
- <p>The base strings for this function can be customized with <code>_date.relativeTime</code>.</p>
+ <h2>Tests</h2>
- <p>The breakdown of which string is displayed when is outlined in the table below.</p>
-
- <table>
- <tr>
- <th>Range</th>
- <th>Key</th>
- <th>Sample Output</th>
- </tr>
- <tr>
- <td>0 to 45 seconds</td>
- <td>s</td>
- <td>seconds ago</td>
- </tr>
- <tr>
- <td>45 to 90 seconds</td>
- <td>m</td>
- <td>a minute ago</td>
- </tr>
- <tr>
- <td>90 seconds to 45 minutes</td>
- <td>mm</td>
- <td>2 minutes ago ... 45 minutes ago</td>
- </tr>
- <tr>
- <td>45 to 90 minutes</td>
- <td>h</td>
- <td>an hour ago</td>
- </tr>
- <tr>
- <td>90 minutes to 22 hours </td>
- <td>hh</td>
- <td>2 hours ago ... 22 hours ago</td>
- </tr>
- <tr>
- <td>22 to 36 hours</td>
- <td>d</td>
- <td>a day ago</td>
- </tr>
- <tr>
- <td>36 hours to 25 days</td>
- <td>dd</td>
- <td>2 days ago ... 25 days ago</td>
- </tr>
- <tr>
- <td>25 to 45 days</td>
- <td>M</td>
- <td>a month ago</td>
- </tr>
- <tr>
- <td>45 to 345 days</td>
- <td>MM</td>
- <td>2 months ago ... 11 months ago</td>
- </tr>
- <tr>
- <td>345 to 547 days (1.5 years)</td>
- <td>y</td>
- <td>a year ago</td>
- </tr>
- <tr>
- <td>548 days+</td>
- <td>yy</td>
- <td>2 years ago ... 20 years ago</td>
- </tr>
- </table>
-
+ <h3 class="col-1"><a href="test/test.html">underscore.date unit tests</a></h3>
- <h2>_date.fromNow()</h2>
-
- <pre><code>_date.fromNow(withoutSuffix:boolean, asMilliseconds:boolean)</code></pre>
-
- <p>Retuns the time from now.</p>
-
- <p>A shortcut for <code>_date.from(_date(), withoutSuffix:boolean, asMilliseconds:boolean)</code>.</p>
-
- <h2>_date.isLeapYear()</h2>
-
- <p>Returns <code>true</code> if the year is a leap year, <code>false</code> if it is not</p>
+ <h3 class="col-1"><a href="http://jsperf.com/underscore-date">underscore.date performance tests</a></h3>
- <p>Examples :</p>
+ <div class="clearfix"></div>
- <pre><code>_date([2000]).isLeapYear() // true
-_date([2001]).isLeapYear() // false
-_date([2100]).isLeapYear() // false</code></pre>
-
- <h2>Localization and Customization</h2>
-
- <p>To customize the wording of <code>_date.format()</code> and <code>_date.from()</code>, the strings are exposed through the _date object. You can modify these however you see fit.</p>
-
- <p>Examples :</p>
-
- <pre><code>_date.relativeTime.future = "%s from now";
-_date.relativeTime.past = "%s in the past";</code></pre>
-
- <h3>_date.relativeTime</h3>
-
- <pre><code>_date.relativeTime = {
- future: "in %s",
- past: "%s ago",
- s: "seconds",
- m: "a minute",
- mm: "%d minutes",
- h: "an hour",
- hh: "%d hours",
- d: "a day",
- dd: "%d days",
- M: "a month",
- MM: "%d months",
- y: "a year",
- yy: "%d years"
-};</code></pre>
-
- <p>The strings used in <code>_date.from()</code>.</p>
-
- <p><code>future</code> and <code>past</code> are used as the suffixes/prefixes.</p>
-
- <p>For all these values, a single character refers to the singular, and an double character refers to the plural.</p>
-
- <h3>_date.weekdays</h3>
-
- <pre><code>_date.weekdays = ["Sunday", "Monday", "Tuesday",
-"Wednesday", "Thursday", "Friday", "Saturday"];</code></pre>
-
- <p>An array of day names, starting with Sunday. </p>
-
- <h3>_date.weekdaysShort</h3>
-
- <pre><code>_date.weekdaysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];</code></pre>
-
- <p>An array of abbreviated day names, starting with Sunday. </p>
-
- <h3>_date.months</h3>
-
- <pre><code>_date.months = ["January", "February", "March", "April", "May",
-"June", "July", "August", "September", "October", "November", "December"];</code></pre>
-
- <p>An array of the names of the months, starting with January.</p>
-
- <h3>_date.monthsShort</h3>
-
- <pre><code>_date.monthsShort = ["Jan", "Feb", "Mar", "Apr", "May",
-"Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];</code></pre>
-
- <p>An array of the abbreviated names of the months, starting with January.</p>
-
- <h3>_date.ordinal</h3>
-
- <pre><code>_date.ordinal = function (number) {
-var b = number % 10;
-return (~~ (number % 100 / 10) === 1) ? 'th' :
- (b === 1) ? 'st' :
- (b === 2) ? 'nd' :
- (b === 3) ? 'rd' : 'th';
-};</code></pre>
-
- <p>A function that returns a string to be appended to the number passed in.
- <a href="http://en.wikipedia.org/wiki/Ordinal_number_%28linguistics%29">More information on ordinal numbers</a></p>
-
- <h1>Tests</h1>
-
- <p><a href="http://timrwood.github.com/underscore.date/test/test.html">Underscore.date unit tests</a></p>
-
- <p><a href="http://jsperf.com/underscore-date">Underscore.date performance tests</a></p>
-
- <h1>Thanks to...</h1>
-
- <p>The folks over at <a href="http://code.google.com/p/datejs/">date.js</a>.</p>
-
- <p>Everyone who helped with <a href="http://phpjs.org/functions/date:380">php.js date</a>.</p>
-
- <p><a href="http://ryan.mcgeary.org/">Ryan McGeary</a> for his work on the <a href="http://timeago.yarp.com/">jQuery timeago plugin</a>.</p>
-
- <h1>License</h1>
-
- <p>Underscore.date is freely distributable under the terms of the MIT license.</p>
-
- <h1>Changelog</h1>
-
- <h3>0.5.2</h3>
-
- <p>Buxfix for <a href="https://github.com/timrwood/underscore.date/pull/8">issue 8</a> and <a href="https://github.com/timrwood/underscore.date/pull/9">issue 9</a>.</p>
-
- <h3>0.5.1</h3>
-
- <p>Buxfix for <a href="https://github.com/timrwood/underscore.date/pull/5">issue 5</a>.</p>
-
- <h3>0.5.0</h3>
-
- <p>Dropped the redundant <code>_date.date()</code> in favor of <code>_date()</code>.
- Removed <code>_date.now()</code>, as it is a duplicate of <code>_date()</code> with no parameters.
- Removed <code>_date.isLeapYear(yearNuumber)</code>. Use <code>_date([yearNumber]).isLeapYear()</code> instead.
- Exposed customization options through the <code>_date.relativeTime</code>, <code>_date.weekdays</code>, <code>_date.weekdaysShort</code>, <code>_date.months</code>, <code>_date.monthsShort</code>, and <code>_date.ordinal</code> variables instead of the <code>_date.customize()</code> function.</p>
-
- <h3>0.4.1</h3>
-
- <p>Added date input formats for input strings.</p>
-
- <h3>0.4.0</h3>
-
- <p>Added underscore.date to npm. Removed dependancies on underscore.</p>
-
- <h3>0.3.2</h3>
-
- <p>Added <code>'z'</code> and <code>'zz'</code> to <code>_.date().format()</code>. Cleaned up some redundant code to trim off some bytes.</p>
-
- <h3>0.3.1</h3>
-
- <p>Cleaned up the namespace. Moved all date manipulation and display functions to the _.date() object. </p>
-
- <h3>0.3.0</h3>
-
- <p>Switched to the Underscore methodology of not mucking with the native objects' prototypes.
- Made chaining possible.</p>
-
- <h3>0.2.1</h3>
-
- <p>Changed date names to be a more pseudo standardized 'dddd, MMMM Do YYYY, h:mm:ss a'.
- Added <code>Date.prototype</code> functions <code>add</code>, <code>subtract</code>, <code>isdst</code>, and <code>isleapyear</code>.</p>
-
- <h3>0.2.0</h3>
-
- <p>Changed function names to be more concise.
- Changed date format from php date format to custom format.</p>
-
- <h3>0.1.0</h3>
-
- <p>Initial release</p>
-
- <div class="footer">
- get the source code on GitHub : <a href="http://github.com/timrwood/underscore.date">timrwood/underscore.date</a>
- </div>
+ <h3>Full source code and documentation at <a href="http://github.com/timrwood/underscore.date">http://github.com/timrwood/underscore.date</a></h3>
</div>
projects / thirdparty / moment.git / commitdiff
