Permalink
Browse files

updating readme to 0.4.0

  • Loading branch information...
1 parent 054751d commit e42b5646948a1c28238084f51ced520637ed0a2e @timrwood timrwood committed May 2, 2011
Showing with 83 additions and 59 deletions.
  1. +83 −59 README.markdown
View
@@ -3,49 +3,69 @@ Underscore.date
Author: Tim Wood
-Version: 0.3.2
+Version: 0.4.0
Underscore.date is a JavaScript Date utility library built on top of [Underscore.js](http://documentcloud.github.com/underscore/)
It adds utility functions for working with Date objects without extending `Date.prototype`.
In addition to the date creation and manipulation functions, there are a few functions for displaying a date in human readable formats.
- _.date(new Date(2010, 1, 14, 15, 25, 50, 125)).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
- _.date(new Date(2010, 1, 14, 15, 25, 50, 125)).fromNow(); // "20 days ago"
+ var someday = new Date(2010, 1, 14, 15, 25, 50, 125);
+ _date.date(someday).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
+ _date.date(someday).fromNow(); // "20 days ago"
-### Filesize : 1.59 kb minified + gzipped
+### Filesize : 1.7 kb minified + gzipped
<table>
<tr>
<th>minified</th>
<th>gzipped</th>
</tr>
<tr>
- <td>3.51 kb</td>
- <td>1.59 kb</td>
+ <td>3.81 kb</td>
+ <td>1.7 kb</td>
</tr>
</table>
-_.date()
-========
+Node.js
+=======
+
+ npm install underscore.date
+
+Usage
+
+ var _date = require('underscore.date');
+ console.log(_date.date('September 9 1999').fromNow());
-The library works by creating a `_Date` date wrapper object using _.date().
+Underscore mixin
+================
+
+If underscore exists, `_date` will mix itself into the underscore namespace, so you can do this:
+
+ _.date('September 9 1999').fromNow()
+
+Otherwise, you should use `_date`.
+
+_date.date()
+============
+
+The library works by creating a `_date.date()` date wrapper object using _date.date().
To create that wrapper, you can pass any of the following data types in.
### Date
- _.date(new Date(2010, 1, 14, 15, 25, 50, 125))
+ _date.date(new Date(2010, 1, 14, 15, 25, 50, 125))
Any valid `Date` object. For more information on `Date` objects, see [the JavaScript Date documentation at MDN](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date)
### Array
- _.date([2010, 1, 14, 15, 25, 50, 125])
+ _date.date([2010, 1, 14, 15, 25, 50, 125])
The array should mirror the parameters passed into [Date.UTC()](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/UTC).
@@ -57,67 +77,67 @@ Any value past the year is optional, and will default to the lowest possible num
### String
- _.date("Dec 25, 1995")
+ _date.date("Dec 25, 1995")
A string that can be parsed by [Date.parse()](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/parse).
### Number
- _.date(1300291340510)
+ _date.date(1300291340510)
An integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.
### undefined
- _.date()
+ _date.date()
If no value is passed to a 'dateInput' parameter, it will default to the current time using `new Date()`.
- _.date() === _.date(new Date())
+ _date.date() === _date.date(new Date())
-_.now()
-=======
+_date.now()
+===========
- _.now(asTimestamp)
+ _date.now(asTimestamp)
Returns the current date.
-Pass `true` to return a UNIX timestamp, otherwise it is just a shortcut to `_.date(new Date())`.
+Pass `true` to return a UNIX timestamp, otherwise it is just a shortcut to `_date.date(new Date())`.
-_.isLeapYear()
-==============
+_date.isLeapYear()
+==================
- _.isLeapYear(number)
+ _date.isLeapYear(number)
Returns `true` if the year is a leap year, `false` if it is not
-Pass the year number to this function. To check for a leap year on a `_.date()` object, use `_.date().isLeapYear()`
+Pass the year number to this function. To check for a leap year on a `_date.date()` object, use `_date.date().isLeapYear()`
Examples :
- _.isLeapYear(2000) // true
- _.isLeapYear(2001) // false
- _.isLeapYear(2100) // false
+ _date.isLeapYear(2000) // true
+ _date.isLeapYear(2001) // false
+ _date.isLeapYear(2100) // false
-_Date Functions
-===============
+_date.date() Functions
+======================
-_Date.add()
+_date.date().add()
-----------
- _.date().add(object)
+ _date.date().add(object)
Adds time per the object passed in.
@@ -144,34 +164,34 @@ If the day of the month on the original date is greater than the number of days
Example:
- _.date([2010, 0, 31]) // January 31
- _.date([2010, 0, 31]).add({M:1}) // February 28
+ _date.date([2010, 0, 31]) // January 31
+ _date.date([2010, 0, 31]).add({M:1}) // February 28
-_Date.subtract()
+_date.date().subtract()
----------------
- _.date().subtract(object)
+ _date.date().subtract(object)
-Functions the same as `_.date().add()`, only using subtraction instead of addition.
+Functions the same as `_date.date().add()`, only using subtraction instead of addition.
Example:
- _.date([2010, 1, 28]) // February 28
- _.date([2010, 1, 28]).subtract({M:1}) // January 28
+ _date.date([2010, 1, 28]) // February 28
+ _date.date([2010, 1, 28]).subtract({M:1}) // January 28
-_Date.format()
+_date.date().format()
--------------
- _Date.format(string)
+ _date.date().format(string)
Returns a human readable string based on the format string that was passed in.
- _.date(new Date(2010, 1, 14, 15, 25, 50, 125)).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
- _.date(new Date(2010, 1, 14, 15, 25, 50, 125)).format("ddd, hA"); // "Sun, 3PM"
+ _date.date(new Date(2010, 1, 14, 15, 25, 50, 125)).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
+ _date.date(new Date(2010, 1, 14, 15, 25, 50, 125)).format("ddd, hA"); // "Sun, 3PM"
The formats are created by creating a string of replacable characters.
@@ -356,57 +376,57 @@ The formats are created by creating a string of replacable characters.
-_Date.from()
+_date.date().from()
------------
- _Date.from(date, withoutSuffix:boolean, asMilliseconds:boolean)
+ _date.date().from(date, withoutSuffix:boolean, asMilliseconds:boolean)
Returns a string as relative time ('minutes ago', '5 months ago', etc).
-You can pass anything that you would pass to _.date() as the first parameter, or a _.date() object.
+You can pass anything that you would pass to _date.date() as the first parameter, or a _date.date() object.
- _.date([2007, 0, 29]).from(_.date([2007, 0, 28])) // "a day ago");
+ _date.date([2007, 0, 29]).from(_date.date([2007, 0, 28])) // "a day ago");
You can pass `true` as the second parameter to return without the prefixes and suffixes.
- _.date([2007, 0, 29]).from(_.date([2007, 0, 28]), true) // "a day");
+ _date.date([2007, 0, 29]).from(_date.date([2007, 0, 28]), true) // "a day");
You can pass `true` 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.
- _.date([2007, 0, 29]).from(_.date([2007, 0, 28]), true , true) // -86400000);
- _.date([2007, 0, 27]).from(_.date([2007, 0, 28]), true , true) // 86400000);
+ _date.date([2007, 0, 29]).from(_date.date([2007, 0, 28]), true , true) // -86400000);
+ _date.date([2007, 0, 27]).from(_date.date([2007, 0, 28]), true , true) // 86400000);
-The base strings for this function can be customized with `_.date().customize()`.
+The base strings for this function can be customized with `_date.date().customize()`.
-_Date.fromNow()
+_date.date().fromNow()
---------------
- _Date.fromNow(withoutSuffix:boolean, asMilliseconds:boolean)
+ _date.date().fromNow(withoutSuffix:boolean, asMilliseconds:boolean)
-A shortcut for `_.date().from(_.now(), withoutSuffix:boolean, asMilliseconds:boolean)`
+A shortcut for `_date.date().from(_date.now(), withoutSuffix:boolean, asMilliseconds:boolean)`
-_Date.isLeapYear()
+_date.date().isLeapYear()
------------------
Returns `true` if the year is a leap year, `false` if it is not
-118N and Customization
-======================
+Localization and Customization
+==============================
-To customize the wording of `_.date().format()` and `_.date().from()` you can use the `_.date().customize()` function, passing in an
+To customize the wording of `_date.date().format()` and `_date.date().from()` you can use the `_date.date().customize()` function, passing in an
object with the parameters you wish to overwrite.
-_.date().customize(object)
+_date.date().customize(object)
--------------------------
- _.date().customize({
+ _date.date().customize({
weekdays:["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
weekdaysShort:["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
months:["January", "February", "March", "April", "May", "June", "July",
@@ -479,7 +499,7 @@ A function that returns a string to be appended to the number passed in.
yy: "%d years"
}
-The strings used in `_.date().from()`.
+The strings used in `_date.date().from()`.
`future` and `past` are used as the suffixes/prefixes.
@@ -509,6 +529,10 @@ Everyone who helped with [php.js date](http://phpjs.org/functions/date:380).
Changelog
---------
+### 0.4.0
+
+Added underscore.date to npm. Removed dependancies on underscore.
+
### 0.3.2
Added `'z'` and `'zz'` to `_.date().format()`. Cleaned up some redundant code to trim off some bytes.

0 comments on commit e42b564

Please sign in to comment.