Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 225 lines (161 sloc) 6.075 kb
e181a8f @TooTallNate Add README
authored
1 node-time
2 =========
3 ### "[time.h][]" bindings for [NodeJS][Node].
80be195 @TooTallNate Use the branch in the Travis-CI image.
authored
4 [![Build Status](https://secure.travis-ci.org/TooTallNate/node-time.png?branch=master)](http://travis-ci.org/TooTallNate/node-time)
e181a8f @TooTallNate Add README
authored
5
6
7 This module offers simple bindings for the C [time.h][] APIs.
e44aab7 @TooTallNate Fix wording in README
authored
8 It also offers an extended native `Date` object with `getTimezone()`
fc550ed @TooTallNate Prefer the `Timezone` functions over the `TimeZone` functions.
authored
9 and `setTimezone()` functions, which aren't normally part of JavaScript.
e181a8f @TooTallNate Add README
authored
10
11
ba0005d @TooTallNate Add npm installation instructions to the README.
authored
12 Installation
13 ------------
14
15 `node-time` is available through npm:
16
4d966ee @TooTallNate Update README.md
authored
17 ``` bash
ba0005d @TooTallNate Add npm installation instructions to the README.
authored
18 $ npm install time
19 ```
20
21
e181a8f @TooTallNate Add README
authored
22 Example
23 -------
24
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
25 ``` javascript
26 var time = require('time');
e181a8f @TooTallNate Add README
authored
27
f9393b2 @TooTallNate Document the new Date constuctor syntax
authored
28 // Create a new Date instance, representing the current instant in time
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
29 var now = new time.Date();
e181a8f @TooTallNate Add README
authored
30
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
31 now.setTimezone("America/Los_Angeles");
32 // `.getDate()`, `.getDay()`, `.getHours()`, etc.
33 // will return values according to UTC-8
e181a8f @TooTallNate Add README
authored
34
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
35 now.setTimezone("America/New_York");
36 // `.getDate()`, `.getDay()`, `.getHours()`, etc.
37 // will return values according to UTC-5
f9393b2 @TooTallNate Document the new Date constuctor syntax
authored
38
39
40 // You can also set the timezone during instantiation
48b410e @TooTallNate Fix syntax in example in README
authored
41 var azDate = new time.Date(2010, 0, 1, 'America/Phoenix');
f9393b2 @TooTallNate Document the new Date constuctor syntax
authored
42 azDate.getTimezone(); // 'America/Phoenix'
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
43 ```
e181a8f @TooTallNate Add README
authored
44
82b6685 @TooTallNate README++
authored
45 ### Extending the global `Date` object
041a582 @TooTallNate README++
authored
46
79c0c25 @TooTallNate README: posessive
authored
47 `node-time` provides a convenient `time.Date` object, which is its own Date
041a582 @TooTallNate README++
authored
48 constructor independent from your own (or the global) Date object. There are often
49 times, however, when you would like the benefits of node-time on *all* Date
50 instances. To extend the global Date object, simply pass it in as an argument to
51 the node-time module when requiring:
52
53 ``` js
54 var time = require('time')(Date);
55
56 var d = new Date();
57 d.setTimezone('UTC');
58 ```
59
e181a8f @TooTallNate Add README
authored
60
61 API
62 ---
63
64
7a4d41c @TooTallNate Better API documentation.
authored
65 ### Date() -> Date
f9393b2 @TooTallNate Document the new Date constuctor syntax
authored
66 #### new time.Date()
12e26a0 @TooTallNate No semicolons in the docs
authored
67 #### new time.Date(millisecondsFromUTC)
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
68 #### new time.Date(dateString [, timezone ])
69 #### new time.Date(year, month, day [, hour, minute, second, millisecond ] [, timezone ])
7a4d41c @TooTallNate Better API documentation.
authored
70
71 A special `Date` constructor that returns a "super" Date instance, that has
26dc85f @TooTallNate Add Date constructor note to README
authored
72 magic _timezone_ capabilities! You can also pass a `timezone` as the last
73 argument in order to have a Date instance in the specified timezone.
7a4d41c @TooTallNate Better API documentation.
authored
74
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
75 ``` javascript
f9393b2 @TooTallNate Document the new Date constuctor syntax
authored
76 var now = new time.Date();
77 var another = new time.Date('Aug 9, 1995', 'UTC');
78 var more = new time.Date(1970, 0, 1, 'Europe/Amsterdam');
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
79 ```
7a4d41c @TooTallNate Better API documentation.
authored
80
81
4e599dd @TooTallNate Document the new 'relative' behavior.
authored
82 #### date.setTimezone(timezone [, relative ]) -> Undefined
7a4d41c @TooTallNate Better API documentation.
authored
83
4e599dd @TooTallNate Document the new 'relative' behavior.
authored
84 Sets the timezone for the `Date` instance. By default this function makes it so
85 that calls to `getHours()`, `getDays()`, `getMinutes()`, etc. will be relative to
86 the timezone specified. If you pass `true` in as the second argument, then
87 instead of adjusting the local "get" functions to match the specified timezone,
88 instead the internal state of the Date instance is changed, such that the local
89 "get" functions retain their values from before the setTimezone call.
7a4d41c @TooTallNate Better API documentation.
authored
90
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
91 ``` javascript
4e599dd @TooTallNate Document the new 'relative' behavior.
authored
92 date.setTimezone("America/Argentina/San_Juan")
93
94 // Default behavior:
95 a = new time.Date()
96 a.toString()
97 // 'Wed Aug 31 2011 09:45:31 GMT-0700 (PDT)'
98 a.setTimezone('UTC')
99 a.toString()
100 // 'Wed Aug 31 2011 16:45:31 GMT+0000 (UTC)'
101
102 // Relative behavior:
103 b = new time.Date()
104 b.toString()
105 // 'Wed Aug 31 2011 10:48:03 GMT-0700 (PDT)'
106 b.setTimezone('UTC', true)
107 b.toString()
108 // 'Wed Aug 31 2011 10:48:03 GMT+0000 (UTC)'
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
109 ```
7a4d41c @TooTallNate Better API documentation.
authored
110
111
fc550ed @TooTallNate Prefer the `Timezone` functions over the `TimeZone` functions.
authored
112 #### date.getTimezone() -> String
7a4d41c @TooTallNate Better API documentation.
authored
113
114 Returns a String containing the currently configured timezone for the date instance.
2fdd2bb @TooTallNate README++
authored
115 This must be called _after_ `setTimezone()` has been called.
7a4d41c @TooTallNate Better API documentation.
authored
116
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
117 ``` javascript
118 date.getTimezone();
119 // "America/Argentina/San_Juan"
120 ```
121
e181a8f @TooTallNate Add README
authored
122
a77ec90 @TooTallNate Document `Date#getTimezoneAbbr()`.
authored
123 #### date.getTimezoneAbbr() -> String
124
125 Returns the abbreviated timezone name, also taking daylight savings into consideration.
0d32c1d @TooTallNate README++
authored
126 Useful for the presentation layer of a Date instance.
a77ec90 @TooTallNate Document `Date#getTimezoneAbbr()`.
authored
127
128 ``` javascript
129 date.getTimezoneAbbr();
130 // "ART"
131 ```
132
133
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
134 ### Date.parse(dateStr [, timezone ]) -> Number
135
136 Same as the native JavaScript `Date.parse()` function, only this version allows
137 for a second, optional, `timezone` argument, which specifies the timezone in
20afc0c @TooTallNate README++
authored
138 which the date string parsing will be resolved against. This function is also
139 aliased as `time.parse()`.
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
140
141 ``` javascript
20afc0c @TooTallNate README++
authored
142 time.Date.parse("1970, January 1"); // <- Local Time
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
143 // 28800000
20afc0c @TooTallNate README++
authored
144 time.Date.parse("1970, January 1", "Europe/Copenhagen");
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
145 // -3600000
20afc0c @TooTallNate README++
authored
146 time.Date.parse("1970, January 1", "UTC");
fe02ee4 @TooTallNate Add documentation for `Date.parse()`.
authored
147 // 0
148 ```
149
150
3909841 @TooTallNate Document the `extend()` function in the README
authored
151 ### extend(date) -> Date
152
153 Transforms a "regular" Date instance into one of `node-time`'s "extended" Date instances.
154
155 ``` javascript
156 var d = new Date();
157 // `d.setTimezone()` does not exist...
158 time.extend(d);
159 d.setTimezone("UTC");
160 ```
161
162
e181a8f @TooTallNate Add README
authored
163 ### time() -> Number
164
7a4d41c @TooTallNate Better API documentation.
authored
165 Binding for `time()`. Returns the number of seconds since Jan 1, 1900 UTC.
166 These two are equivalent:
e181a8f @TooTallNate Add README
authored
167
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
168 ``` javascript
169 time.time();
170 // 1299827226
171 Math.floor(Date.now() / 1000);
172 // 1299827226
173 ```
e181a8f @TooTallNate Add README
authored
174
175
7a4d41c @TooTallNate Better API documentation.
authored
176 ### tzset(timezone) -> Object
177
178 Binding for `tzset()`. Sets up the timezone information that `localtime()` will
179 use based on the specified _timezone_ variable, or the current `process.env.TZ`
180 value if none is specified. Returns an Object containing information about the
181 newly set timezone, or throws an Error if no timezone information could be loaded
182 for the specified timezone.
183
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
184 ``` javascript
185 time.tzset('US/Pacific');
186 // { tzname: [ 'PST', 'PDT' ],
187 // timezone: 28800,
188 // daylight: 1 }
189 ```
e181a8f @TooTallNate Add README
authored
190
191
6c0c868 @TooTallNate Edited README.md via GitHub
authored
192 ### localtime(Number) -> Object
e181a8f @TooTallNate Add README
authored
193
194 Binding for `localtime()`. Accepts a Number with the number of seconds since the
195 Epoch (i.e. the result of `time()`), and returns a "broken-down" Object
196 representation of the timestamp, according the the currently configured timezone
197 (see `tzset()`).
198
785f097 @TooTallNate Use the new GitHub syntax highlighting Markdown format in the README
authored
199 ``` javascript
200 time.localtime(Date.now()/1000);
201 // { seconds: 38,
202 // minutes: 7,
203 // hours: 23,
204 // dayOfMonth: 10,
205 // month: 2,
206 // year: 111,
207 // dayOfWeek: 4,
208 // dayOfYear: 68,
209 // isDaylightSavings: false,
210 // gmtOffset: -28800,
211 // timezone: 'PST' }
212 ```
7a4d41c @TooTallNate Better API documentation.
authored
213
e181a8f @TooTallNate Add README
authored
214
36d3a1c @TooTallNate Add documentation for `currentTimezone`.
authored
215 ### currentTimezone -> String
216
217 The `currentTimezone` property always contains a String to the current timezone
218 being used by `node-time`. This property is reset every time the `tzset()`
219 function is called. Individual `time.Date` instances may have independent
220 timezone settings than what this one is...
221
222
e181a8f @TooTallNate Add README
authored
223 [Node]: http://nodejs.org
224 [time.h]: http://en.wikipedia.org/wiki/Time.h
Something went wrong with that request. Please try again.