1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
|
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>calendar</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>calendar</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
calendar</UL>
<H3>MODULE SUMMARY</H3>
<UL>
Local and universal time, day-of-the-week, date and time
conversions</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>This module provides computation of local and universal time,
day-of-the-week, and several time conversion functions.
<P>Time is local when it is adjusted in accordance with the
current time zone and daylight saving. Time is universal when it
reflects the time at longitude zero, without any adjustment for
daylight saving. Universal Coordinated Time (UTC) time is also
called Greenwich Mean Time (GMT).
<P>The time functions <CODE>local_time/0</CODE> and <CODE>universal_time/0</CODE>
provided in this module both return date and time. The reason for
this is that separate functions for date and time may result in a
date/time combination which is displaced by 24 hours. This happens
if one of the functions is called before midnight, and the other
after midnight. This problem also applies to the Erlang BIFs
<CODE>date/0</CODE> and <CODE>time/0</CODE>, and their use is strongly
discouraged if a reliable date/time stamp is required.
<P>All dates conform to the Gregorian calendar. This calendar
was introduced by Pope Gregory XIII in 1582 and was used in all
Catholic countries from this year. Protestant parts of Germany and the
Netherlands adopted it in 1698, England followed in 1752, and Russia
in 1918 (the October revolution of 1917 took place in November
according to the Gregorian calendar).<P>The Gregorian calendar in this module is extended back to year 0.
For a given date, the <STRONG>gregorian days</STRONG> is the number of days
up to and including the date specified. Similarly, the <STRONG>gregorian
seconds</STRONG> for a given date and time, is the the number of seconds
up to and including the specified date and time.
<P>For computing differences between epochs in time, use the functions
counting gregorian days or seconds. If epochs are given as local time,
they must be converted to universal time, in order to get the correct
value of the elapsed time between epochs. Use of the function
<CODE>time_difference/2</CODE> is discouraged.
</UL>
<H3>EXPORTS</H3>
<P><A NAME="date_to_gregorian_days%3"><STRONG><CODE>date_to_gregorian_days(Year, Month, Day) -> Days</CODE></STRONG></A><BR>
<A NAME="date_to_gregorian_days%1"><STRONG><CODE>date_to_gregorian_days(Date) -> Days</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Days = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the number of gregorian days starting
with year 0 and ending at the given date.
</UL>
<P><A NAME="datetime_to_gregorian_seconds%1"><STRONG><CODE>datetime_to_gregorian_seconds(DateTime) -> Days</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>DateTime = {date(), time()}</CODE></STRONG><BR>
<STRONG><CODE>date() = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = Days = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the number of gregorian seconds starting
with year 0 and ending at the given date and time.
</UL>
<P><A NAME="day_of_the_week%1"><STRONG><CODE>day_of_the_week(Date) -> DayNumber</CODE></STRONG></A><BR>
<A NAME="day_of_the_week%3"><STRONG><CODE>day_of_the_week(Year, Month, Day) -> DayNumber</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = DayNumber = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the day of the week given
<CODE>Year</CODE>, <CODE>Month</CODE>
and <CODE>Day</CODE>. The return value denotes the day of the week as
follows: <PRE>Monday = 1, Tuesday = 2, ..., Sunday = 7</PRE>
<P><CODE>Year</CODE> cannot be abbreviated and a value of 93 denotes
the year 93, and not the year 1993. <CODE>Month</CODE> is the month
number with January = 1. <CODE>Day</CODE> is an integer in the range
1 and the number of days in the month <CODE>Month</CODE> of the
year <CODE>Year</CODE>.
</UL>
<P><A NAME="gregorian_days_to_date%1"><STRONG><CODE>gregorian_days_to_date(Days) -> Date</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Days = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the date given the number of gregorian
days.
</UL>
<P><A NAME="gregorian_seconds_to_datetime%1"><STRONG><CODE>gregorian_seconds_to_datetime(Secs) -> DateTime</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>DateTime = {date(), time()}</CODE></STRONG><BR>
<STRONG><CODE>date() = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = Days = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the date and time from the given number
of gregorian seconds.
</UL>
<P><A NAME="is_leap_year%1"><STRONG><CODE>is_leap_year(Year) -> bool()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Year = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function checks if a year is a leap year.
</UL>
<P><A NAME="last_day_of_the_month%2"><STRONG><CODE>last_day_of_the_month(Year, Month) -> int()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Year = Month = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the number of days in a month.
</UL>
<P><A NAME="local_time%0"><STRONG><CODE>local_time() -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns the local time reported by the
underlying operating system.
</UL>
<P><A NAME="local_time_to_universal_time%2"><STRONG><CODE>local_time_to_universal_time({Date, Time}) -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function converts from local time to Universal
Coordinated Time (UTC). <CODE>Date</CODE> must refer to a local date
after Jan 1, 1970.</UL>
<P><A NAME="now_to_local_time%1"><STRONG><CODE>now_to_local_time(Now) -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Now = {MegaSecs, Secs, MicroSecs}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>MegaSecs = Secs = MilliSecs = int()</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns local date and time
converted from the return value from <CODE>erlang:now()</CODE>.
</UL>
<P><A NAME="now_to_universal_time%1"><STRONG><CODE>now_to_universal_time(Now) -> {Date, Time}</CODE></STRONG></A><BR>
<A NAME="now_to_datetime%1"><STRONG><CODE>now_to_datetime(Now) -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Now = {MegaSecs, Secs, MicroSecs}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>MegaSecs = Secs = MilliSecs = int()</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns Universal Coordinated Time (UTC)
converted from the return value from <CODE>erlang:now()</CODE>.
</UL>
<P><A NAME="seconds_to_daystime%1"><STRONG><CODE>seconds_to_daystime(Secs) -> {Days, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Days = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function transforms a given number of seconds into
days, hours, minutes, and seconds. The <CODE>Time</CODE> part
is always non-negative, but <CODE>Days</CODE> is negative
if the argument <CODE>Secs</CODE> is.
</UL>
<P><A NAME="seconds_to_time%1"><STRONG><CODE>seconds_to_time(Secs) -> Time</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Secs = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the time from the given number of
seconds. <CODE>Secs</CODE> must be less than the number of seconds
per day.
</UL>
<P><A NAME="time_difference%2"><STRONG><CODE>time_difference(T1, T2) -> Tdiff</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>T1 = T2 = {Date, Time}</CODE></STRONG><BR>
<STRONG><CODE>Tdiff = {Day, {Hour, Minute, Second}}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns the difference between two <CODE>{Date,
Time}</CODE> structures. <CODE>T2</CODE> should refer to an epoch later
than <CODE>T1</CODE>.
<P>This function is obsolete. Use the conversion functions for
gregorian days and seconds instead.</UL>
<P><A NAME="time_to_secnds%1"><STRONG><CODE>time_to_secnds(Time) -> Secs</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Secs = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function computes the number of seconds since midnight
up to the specified time. </UL>
<P><A NAME="universal_time%0"><STRONG><CODE>universal_time() -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns the Universal Coordinated Time (UTC)
reported by the underlying operating system. Local time is
returned if universal time is not available.
</UL>
<P><A NAME="universal_time_to_local_time%2"><STRONG><CODE>universal_time_to_local_time({Date, Time}) -> {Date, Time}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function converts from Universal Coordinated Time (UTC)
to local time. <CODE>Date</CODE> must refer to a date after Jan 1,
1970.</UL>
<P><A NAME="valid_date%1"><STRONG><CODE>valid_date(Date) -> bool()</CODE></STRONG></A><BR>
<A NAME="valid_date%3"><STRONG><CODE>valid_date(Year, Month, Day) -> bool()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function checks if a date is a valid.
</UL>
<H3>Leap Years</H3>
<UL>
<P>The notion that every fourth year is a leap year is not
completely true. By the Gregorian rule, a year Y is a leap year if
either of the following rules is valid:
<P><UL>
<LI>Y is divisible by 4, but not by 100; or
<BR>
</LI><BR>
<LI>Y is divisible by 400.
<BR>
</LI><BR>
</UL>
<P>Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.
</UL>
<H3>Date and Time Source</H3>
<UL>
<P>Local time is obtained from the Erlang BIF <CODE>localtime/0</CODE>.
Universal time is computed from the BIF <CODE>universaltime/0</CODE>.
<P>The following facts apply:<P><UL>
<LI>there are 86400 seconds in a day</LI><BR>
<LI>there are 365 days in an ordinary year</LI><BR>
<LI>there are 366 days in a leap year</LI><BR>
<LI>there are 1461 days in a 4 year period</LI><BR>
<LI>there are 36524 days in a 100 year period</LI><BR>
<LI>there are 146097 days in a 400 year period</LI><BR>
<LI>there are 719528 days between Jan 1, 0 and Jan 1, 1970.</LI><BR>
</UL>
</UL>
<H3>AUTHORS</H3>
<UL>
Peter Högfeldt - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright © 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>
|
