1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>calendar</title>
27
<prepared>Peter Högfeldt</prepared>
29
<date>1996-11-05</date>
32
<module>calendar</module>
33
<modulesummary>Local and universal time, day-of-the-week, date and time conversions</modulesummary>
35
<p>This module provides computation of local and universal time,
36
day-of-the-week, and several time conversion functions.</p>
37
<p>Time is local when it is adjusted in accordance with the current
38
time zone and daylight saving. Time is universal when it reflects
39
the time at longitude zero, without any adjustment for daylight
40
saving. Universal Coordinated Time (UTC) time is also called
41
Greenwich Mean Time (GMT).</p>
42
<p>The time functions <c>local_time/0</c> and
43
<c>universal_time/0</c> provided in this module both return date
44
and time. The reason for this is that separate functions for date
45
and time may result in a date/time combination which is displaced
46
by 24 hours. This happens if one of the functions is called
47
before midnight, and the other after midnight. This problem also
48
applies to the Erlang BIFs <c>date/0</c> and <c>time/0</c>, and
49
their use is strongly discouraged if a reliable date/time stamp
51
<p>All dates conform to the Gregorian calendar. This calendar was
52
introduced by Pope Gregory XIII in 1582 and was used in all
53
Catholic countries from this year. Protestant parts of Germany
54
and the Netherlands adopted it in 1698, England followed in 1752,
55
and Russia in 1918 (the October revolution of 1917 took place in
56
November according to the Gregorian calendar).</p>
57
<p>The Gregorian calendar in this module is extended back to year 0.
58
For a given date, the <em>gregorian days</em> is the number of
59
days up to and including the date specified. Similarly,
60
the <em>gregorian seconds</em> for a given date and time, is
61
the the number of seconds up to and including the specified date
63
<p>For computing differences between epochs in time, use
64
the functions counting gregorian days or seconds. If epochs are
65
given as local time, they must be converted to universal time, in
66
order to get the correct value of the elapsed time between epochs.
67
Use of the function <c>time_difference/2</c> is discouraged.</p>
71
<title>DATA TYPES</title>
73
date() = {Year, Month, Day}
77
Year cannot be abbreviated. Example: 93 denotes year 93, not 1993.
78
Valid range depends on the underlying OS.
79
The date tuple must denote a valid date.
81
time() = {Hour, Minute, Second}
83
Minute = Second = 0..59</code>
87
<name>date_to_gregorian_days(Date) -> Days</name>
88
<name>date_to_gregorian_days(Year, Month, Day) -> Days</name>
89
<fsummary>Compute the number of days from year 0 up to the given date</fsummary>
95
<p>This function computes the number of gregorian days starting
96
with year 0 and ending at the given date.</p>
100
<name>datetime_to_gregorian_seconds({Date, Time}) -> Seconds</name>
101
<fsummary>Compute the number of seconds from year 0 up to the given date and time</fsummary>
105
<v>Seconds = int()</v>
108
<p>This function computes the number of gregorian seconds
109
starting with year 0 and ending at the given date and time.</p>
113
<name>day_of_the_week(Date) -> DayNumber</name>
114
<name>day_of_the_week(Year, Month, Day) -> DayNumber</name>
115
<fsummary>Compute the day of the week</fsummary>
118
<v>DayNumber = 1..7</v>
121
<p>This function computes the day of the week given <c>Year</c>,
122
<c>Month</c> and <c>Day</c>. The return value denotes the day
123
of the week as <c>1</c>: Monday, <c>2</c>: Tuesday, and so on.</p>
127
<name>gregorian_days_to_date(Days) -> Date</name>
128
<fsummary>Compute the date given the number of gregorian days</fsummary>
134
<p>This function computes the date given the number of
139
<name>gregorian_seconds_to_datetime(Seconds) -> {Date, Time}</name>
140
<fsummary>Compute the date given the number of gregorian days</fsummary>
142
<v>Seconds = int()</v>
147
<p>This function computes the date and time from the given
148
number of gregorian seconds.</p>
152
<name>is_leap_year(Year) -> bool()</name>
153
<fsummary>Check if a year is a leap year</fsummary>
155
<p>This function checks if a year is a leap year.</p>
159
<name>last_day_of_the_month(Year, Month) -> int()</name>
160
<fsummary>Compute the number of days in a month</fsummary>
162
<p>This function computes the number of days in a month.</p>
166
<name>local_time() -> {Date, Time}</name>
167
<fsummary>Compute local time</fsummary>
173
<p>This function returns the local time reported by
174
the underlying operating system.</p>
178
<name>local_time_to_universal_time({Date1, Time1}) -> {Date2, Time2}</name>
179
<fsummary>Convert from local time to universal time (deprecated)</fsummary>
181
<p>This function converts from local time to Universal
182
Coordinated Time (UTC). <c>Date1</c> must refer to a local
183
date after Jan 1, 1970.</p>
185
<p>This function is deprecated. Use
186
<c>local_time_to_universal_time_dst/1</c> instead, as it
187
gives a more correct and complete result. Especially for
188
the period that does not exist since it gets skipped during
189
the switch <em>to</em> daylight saving time, this function
190
still returns a result.</p>
195
<name>local_time_to_universal_time_dst({Date1, Time1}) -> [{Date, Time}]</name>
196
<fsummary>Convert from local time to universal time(s)</fsummary>
198
<v>Date1 = Date = date()</v>
199
<v>Time1 = Time = time()</v>
202
<p>This function converts from local time to Universal
203
Coordinated Time (UTC). <c>Date1</c> must refer to a local
204
date after Jan 1, 1970.</p>
205
<p>The return value is a list of 0, 1 or 2 possible UTC times:</p>
209
<p>For a local <c>{Date1, Time1}</c> during the period that
210
is skipped when switching <em>to</em> daylight saving
211
time, there is no corresponding UTC since the local time
212
is illegal - it has never happened.</p>
214
<tag><c>[DstDateTimeUTC, DateTimeUTC]</c></tag>
216
<p>For a local <c>{Date1, Time1}</c> during the period that
217
is repeated when switching <em>from</em> daylight saving
218
time, there are two corresponding UTCs. One for the first
219
instance of the period when daylight saving time is still
220
active, and one for the second instance.</p>
222
<tag><c>[DateTimeUTC]</c></tag>
224
<p>For all other local times there is only one
225
corresponding UTC.</p>
231
<name>now_to_local_time(Now) -> {Date, Time}</name>
232
<fsummary>Convert now to local date and time</fsummary>
234
<v>Now -- see erlang:now/0</v>
239
<p>This function returns local date and time converted from
240
the return value from <c>erlang:now()</c>.</p>
244
<name>now_to_universal_time(Now) -> {Date, Time}</name>
245
<name>now_to_datetime(Now) -> {Date, Time}</name>
246
<fsummary>Convert now to date and time</fsummary>
248
<v>Now -- see erlang:now/0</v>
253
<p>This function returns Universal Coordinated Time (UTC)
254
converted from the return value from <c>erlang:now()</c>.</p>
258
<name>seconds_to_daystime(Seconds) -> {Days, Time}</name>
259
<fsummary>Compute days and time from seconds</fsummary>
261
<v>Seconds = Days = int()</v>
265
<p>This function transforms a given number of seconds into days,
266
hours, minutes, and seconds. The <c>Time</c> part is always
267
non-negative, but <c>Days</c> is negative if the argument
268
<c>Seconds</c> is.</p>
272
<name>seconds_to_time(Seconds) -> Time</name>
273
<fsummary>Compute time from seconds</fsummary>
275
<v>Seconds = int() < 86400</v>
279
<p>This function computes the time from the given number of
280
seconds. <c>Seconds</c> must be less than the number of
281
seconds per day (86400).</p>
285
<name>time_difference(T1, T2) -> {Days, Time}</name>
286
<fsummary>Compute the difference between two times (deprecated)</fsummary>
288
<p>This function returns the difference between two <c>{Date, Time}</c> tuples. <c>T2</c> should refer to an epoch later
291
<p>This function is obsolete. Use the conversion functions for
292
gregorian days and seconds instead.</p>
297
<name>time_to_seconds(Time) -> Seconds</name>
298
<fsummary>Compute the number of seconds since midnight up to the given time</fsummary>
301
<v>Seconds = int()</v>
304
<p>This function computes the number of seconds since midnight
305
up to the specified time.</p>
309
<name>universal_time() -> {Date, Time}</name>
310
<fsummary>Compute universal time</fsummary>
316
<p>This function returns the Universal Coordinated Time (UTC)
317
reported by the underlying operating system. Local time is
318
returned if universal time is not available.</p>
322
<name>universal_time_to_local_time({Date1, Time1}) -> {Date2, Time2}</name>
323
<fsummary>Convert from universal time to local time</fsummary>
325
<v>Date1 = Date2 = date()</v>
326
<v>Time1 = Time2 = time()</v>
329
<p>This function converts from Universal Coordinated Time (UTC)
330
to local time. <c>Date1</c> must refer to a date after Jan 1,
335
<name>valid_date(Date) -> bool()</name>
336
<name>valid_date(Year, Month, Day) -> bool()</name>
337
<fsummary>Check if a date is valid</fsummary>
342
<p>This function checks if a date is a valid.</p>
348
<title>Leap Years</title>
349
<p>The notion that every fourth year is a leap year is not
350
completely true. By the Gregorian rule, a year Y is a leap year if
351
either of the following rules is valid:</p>
352
<list type="bulleted">
354
<p>Y is divisible by 4, but not by 100; or</p>
357
<p>Y is divisible by 400.</p>
360
<p>Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.</p>
364
<title>Date and Time Source</title>
365
<p>Local time is obtained from the Erlang BIF <c>localtime/0</c>.
366
Universal time is computed from the BIF <c>universaltime/0</c>.</p>
367
<p>The following facts apply:</p>
368
<list type="bulleted">
369
<item>there are 86400 seconds in a day</item>
370
<item>there are 365 days in an ordinary year</item>
371
<item>there are 366 days in a leap year</item>
372
<item>there are 1461 days in a 4 year period</item>
373
<item>there are 36524 days in a 100 year period</item>
374
<item>there are 146097 days in a 400 year period</item>
375
<item>there are 719528 days between Jan 1, 0 and Jan 1, 1970.</item>
added
removed
lib/stdlib/doc/src/calendar.xml
