1calendar(3)                Erlang Module Definition                calendar(3)
2
3
4

NAME

6       calendar - Local and universal time, day of the week, date and time
7           conversions.
8

DESCRIPTION

10       This  module  provides  computation of local and universal time, day of
11       the week, and many time conversion functions.
12
13       Time is local when it is adjusted in accordance with the  current  time
14       zone  and  daylight saving. Time is universal when it reflects the time
15       at longitude zero, without any adjustment for daylight saving.  Univer‐
16       sal  Coordinated  Time  (UTC)  time  is also called Greenwich Mean Time
17       (GMT).
18
19       The time functions local_time/0 and  universal_time/0  in  this  module
20       both  return  date and time. The is because separate functions for date
21       and time can result in a date/time combination that is displaced by  24
22       hours.  This  occurs if one of the functions is called before midnight,
23       and the other after midnight. This problem also applies to  the  Erlang
24       BIFs  date/0  and  time/0,  and  their use is strongly discouraged if a
25       reliable date/time stamp is required.
26
27       All dates conform to the Gregorian calendar. This calendar  was  intro‐
28       duced  by  Pope Gregory XIII in 1582 and was used in all Catholic coun‐
29       tries from this year. Protestant parts of Germany and  the  Netherlands
30       adopted  it  in 1698, England followed in 1752, and Russia in 1918 (the
31       October revolution of 1917 took place in November according to the Gre‐
32       gorian calendar).
33
34       The Gregorian calendar in this module is extended back to year 0. For a
35       given date, the gregorian days is the number of days up to and  includ‐
36       ing  the  date specified. Similarly, the gregorian seconds for a speci‐
37       fied date and time is the number of seconds up  to  and  including  the
38       specified date and time.
39
40       For  computing  differences  between  epochs in time, use the functions
41       counting gregorian days or seconds. If epochs are  specified  as  local
42       time, they must be converted to universal time to get the correct value
43       of the elapsed time between epochs. Use of  function  time_difference/2
44       is discouraged.
45
46       Different  definitions exist for the week of the year. This module con‐
47       tains a week of the year implementation  conforming  to  the  ISO  8601
48       standard.  As the week number for a specified date can fall on the pre‐
49       vious, the current, or on the next year, it  is  important  to  specify
50       both  the  year  and  the  week number. Functions iso_week_number/0 and
51       iso_week_number/1 return a tuple of the year and the week number.
52

DATA TYPES

54       datetime() = {date(), time()}
55
56       datetime1970() = {{year1970(), month(), day()}, time()}
57
58       date() = {year(), month(), day()}
59
60       year() = integer() >= 0
61
62              Year cannot be abbreviated. For example, 93 denotes year 93, not
63              1993.  The  valid range depends on the underlying operating sys‐
64              tem. The date tuple must denote a valid date.
65
66       year1970() = 1970..10000
67
68       month() = 1..12
69
70       day() = 1..31
71
72       time() = {hour(), minute(), second()}
73
74       hour() = 0..23
75
76       minute() = 0..59
77
78       second() = 0..59
79
80       daynum() = 1..7
81
82       ldom() = 28 | 29 | 30 | 31
83
84       yearweeknum() = {year(), weeknum()}
85
86       weeknum() = 1..53
87

EXPORTS

89       date_to_gregorian_days(Date) -> Days
90
91       date_to_gregorian_days(Year, Month, Day) -> Days
92
93              Types:
94
95                 Date = date()
96                 Year = year()
97                 Month = month()
98                 Day = day()
99
100              Computes the number of gregorian days starting with year  0  and
101              ending at the specified date.
102
103       datetime_to_gregorian_seconds(DateTime) -> Seconds
104
105              Types:
106
107                 DateTime = datetime()
108                 Seconds = integer() >= 0
109
110              Computes  the  number  of gregorian seconds starting with year 0
111              and ending at the specified date and time.
112
113       day_of_the_week(Date) -> daynum()
114
115       day_of_the_week(Year, Month, Day) -> daynum()
116
117              Types:
118
119                 Date = date()
120                 Year = year()
121                 Month = month()
122                 Day = day()
123
124              Computes the day of the week from the specified Year, Month, and
125              Day.  Returns  the day of the week as 1: Monday, 2: Tuesday, and
126              so on.
127
128       gregorian_days_to_date(Days) -> date()
129
130              Types:
131
132                 Days = integer() >= 0
133
134              Computes the date from the specified number of gregorian days.
135
136       gregorian_seconds_to_datetime(Seconds) -> datetime()
137
138              Types:
139
140                 Seconds = integer() >= 0
141
142              Computes the date and time from the specified number  of  grego‐
143              rian seconds.
144
145       is_leap_year(Year) -> boolean()
146
147              Types:
148
149                 Year = year()
150
151              Checks if the specified year is a leap year.
152
153       iso_week_number() -> yearweeknum()
154
155              Returns  tuple  {Year, WeekNum} representing the ISO week number
156              for the actual date. To determine the actual date, use  function
157              local_time/0.
158
159       iso_week_number(Date) -> yearweeknum()
160
161              Types:
162
163                 Date = date()
164
165              Returns  tuple  {Year, WeekNum} representing the ISO week number
166              for the specified date.
167
168       last_day_of_the_month(Year, Month) -> LastDay
169
170              Types:
171
172                 Year = year()
173                 Month = month()
174                 LastDay = ldom()
175
176              Computes the number of days in a month.
177
178       local_time() -> datetime()
179
180              Returns the local time reported by the underlying operating sys‐
181              tem.
182
183       local_time_to_universal_time(DateTime1) -> DateTime2
184
185              Types:
186
187                 DateTime1 = DateTime2 = datetime1970()
188
189              Converts  from  local  time to Universal Coordinated Time (UTC).
190              DateTime1 must refer to a local date after Jan 1, 1970.
191
192          Warning:
193              This   function   is   deprecated.   Use   local_time_to_univer‐
194              sal_time_dst/1  instead, as it gives a more correct and complete
195              result. Especially for the period that does not exist, as it  is
196              skipped during the switch to daylight saving time, this function
197              still returns a result.
198
199
200       local_time_to_universal_time_dst(DateTime1) -> [DateTime]
201
202              Types:
203
204                 DateTime1 = DateTime = datetime1970()
205
206              Converts from local time to Universal  Coordinated  Time  (UTC).
207              DateTime1 must refer to a local date after Jan 1, 1970.
208
209              The return value is a list of 0, 1, or 2 possible UTC times:
210
211                []:
212                  For a local {Date1, Time1} during the period that is skipped
213                  when switching to daylight saving time, there is  no  corre‐
214                  sponding  UTC,  as  the  local time is illegal (it has never
215                  occured).
216
217                [DstDateTimeUTC, DateTimeUTC]:
218                  For a  local  {Date1,  Time1}  during  the  period  that  is
219                  repeated  when switching from daylight saving time, two cor‐
220                  responding UTCs exist; one for the  first  instance  of  the
221                  period  when  daylight  saving time is still active, and one
222                  for the second instance.
223
224                [DateTimeUTC]:
225                  For all other local times only one corresponding UTC exists.
226
227       now_to_datetime(Now) -> datetime1970()
228
229              Types:
230
231                 Now = erlang:timestamp()
232
233              Returns Universal Coordinated  Time  (UTC)  converted  from  the
234              return value from erlang:timestamp/0.
235
236       now_to_local_time(Now) -> datetime1970()
237
238              Types:
239
240                 Now = erlang:timestamp()
241
242              Returns local date and time converted from the return value from
243              erlang:timestamp/0.
244
245       now_to_universal_time(Now) -> datetime1970()
246
247              Types:
248
249                 Now = erlang:timestamp()
250
251              Returns Universal Coordinated  Time  (UTC)  converted  from  the
252              return value from erlang:timestamp/0.
253
254       rfc3339_to_system_time(DateTimeString) -> integer()
255
256       rfc3339_to_system_time(DateTimeString, Options) -> integer()
257
258              Types:
259
260                 DateTimeString = rfc3339_string()
261                 Options = [Option]
262                 Option = {unit, rfc3339_time_unit()}
263                 rfc3339_string() = [byte(), ...]
264                 rfc3339_time_unit() =
265                     microsecond | millisecond | nanosecond | second
266
267              Converts an RFC 3339 timestamp into system time. The data format
268              of RFC 3339 timestamps is described by RFC 3339.
269
270              Valid option:
271
272                {unit, Unit}:
273                  The time unit of the return value. The default is second.
274
275              1> calendar:rfc3339_to_system_time("2018-02-01T16:17:58+01:00").
276              1517498278
277              2> calendar:rfc3339_to_system_time("2018-02-01 15:18:02.088Z", [{unit, nanosecond}]).
278              1517498282088000000
279
280       seconds_to_daystime(Seconds) -> {Days, Time}
281
282              Types:
283
284                 Seconds = Days = integer()
285                 Time = time()
286
287              Converts a specified number of seconds into  days,  hours,  min‐
288              utes, and seconds. Time is always non-negative, but Days is neg‐
289              ative if argument Seconds is.
290
291       seconds_to_time(Seconds) -> time()
292
293              Types:
294
295                 Seconds = secs_per_day()
296                 secs_per_day() = 0..86400
297
298              Computes the time from the specified number of seconds.  Seconds
299              must be less than the number of seconds per day (86400).
300
301       system_time_to_local_time(Time, TimeUnit) -> datetime()
302
303              Types:
304
305                 Time = integer()
306                 TimeUnit = erlang:time_unit()
307
308              Converts a specified system time into local date and time.
309
310       system_time_to_rfc3339(Time) -> DateTimeString
311
312       system_time_to_rfc3339(Time, Options) -> DateTimeString
313
314              Types:
315
316                 Time = integer()
317                 Options = [Option]
318                 Option =
319                     {offset, offset()} |
320                     {time_designator, byte()} |
321                     {unit, rfc3339_time_unit()}
322                 DateTimeString = rfc3339_string()
323                 offset() = [byte()] | (Time :: integer())
324                 rfc3339_string() = [byte(), ...]
325                 rfc3339_time_unit() =
326                     microsecond | millisecond | nanosecond | second
327
328              Converts a system time into an RFC 3339 timestamp. The data for‐
329              mat of RFC 3339 timestamps is described by RFC  3339.  The  data
330              format of offsets is also described by RFC 3339.
331
332              Valid options:
333
334                {offset, Offset}:
335                  The offset, either a string or an integer, to be included in
336                  the formatted string. An empty string, which is the default,
337                  is interpreted as local time. A non-empty string is included
338                  as is. The time unit of the integer is the same as  the  one
339                  of Time.
340
341                {time_designator, Character}:
342                  The character used as time designator, that is, the date and
343                  time separator. The default is $T.
344
345                {unit, Unit}:
346                  The time unit of Time. The default is second. If some  other
347                  unit is given (millisecond, microsecond, or nanosecond), the
348                  formatted string includes a fraction of a second. The number
349                  of fractional second digits is three, six, or nine depending
350                  on what time unit is chosen. Notice that trailing zeros  are
351                  not removed from the fraction.
352
353              1> calendar:system_time_to_rfc3339(erlang:system_time(second)).
354              "2018-04-23T14:56:28+02:00"
355              2> calendar:system_time_to_rfc3339(erlang:system_time(second), [{offset, "-02:00"}]).
356              "2018-04-23T10:56:52-02:00"
357              3> calendar:system_time_to_rfc3339(erlang:system_time(second), [{offset, -7200}]).
358              "2018-04-23T10:57:05-02:00"
359              4> calendar:system_time_to_rfc3339(erlang:system_time(millisecond), [{unit, millisecond}, {time_designator, $\s}, {offset, "Z"}]).
360              "2018-04-23 12:57:20.482Z"
361
362       system_time_to_universal_time(Time, TimeUnit) -> datetime()
363
364              Types:
365
366                 Time = integer()
367                 TimeUnit = erlang:time_unit()
368
369              Converts a specified system time into universal date and time.
370
371       time_difference(T1, T2) -> {Days, Time}
372
373              Types:
374
375                 T1 = T2 = datetime()
376                 Days = integer()
377                 Time = time()
378
379              Returns the difference between two {Date, Time} tuples. T2 is to
380              refer to an epoch later than T1.
381
382          Warning:
383              This function is obsolete. Use the conversion functions for gre‐
384              gorian days and seconds instead.
385
386
387       time_to_seconds(Time) -> secs_per_day()
388
389              Types:
390
391                 Time = time()
392                 secs_per_day() = 0..86400
393
394              Returns the number of seconds since midnight up to the specified
395              time.
396
397       universal_time() -> datetime()
398
399              Returns the Universal Coordinated Time  (UTC)  reported  by  the
400              underlying  operating  system.  Returns  local time if universal
401              time is unavailable.
402
403       universal_time_to_local_time(DateTime) -> datetime()
404
405              Types:
406
407                 DateTime = datetime1970()
408
409              Converts from Universal Coordinated Time (UTC)  to  local  time.
410              DateTime must refer to a date after Jan 1, 1970.
411
412       valid_date(Date) -> boolean()
413
414       valid_date(Year, Month, Day) -> boolean()
415
416              Types:
417
418                 Date = date()
419                 Year = Month = Day = integer()
420
421              This function checks if a date is a valid.
422

LEAP YEARS

424       The  notion  that  every  fourth  year is a leap year is not completely
425       true. By the Gregorian rule, a year Y is a leap year if one of the fol‐
426       lowing rules is valid:
427
428         * Y is divisible by 4, but not by 100.
429
430         * Y is divisible by 400.
431
432       Hence, 1996 is a leap year, 1900 is not, but 2000 is.
433

DATE AND TIME SOURCE

435       Local  time is obtained from the Erlang BIF localtime/0. Universal time
436       is computed from the BIF universaltime/0.
437
438       The following apply:
439
440         * There are 86400 seconds in a day.
441
442         * There are 365 days in an ordinary year.
443
444         * There are 366 days in a leap year.
445
446         * There are 1461 days in a 4 year period.
447
448         * There are 36524 days in a 100 year period.
449
450         * There are 146097 days in a 400 year period.
451
452         * There are 719528 days between Jan 1, 0 and Jan 1, 1970.
453
454Ericsson AB                       stdlib 3.10                      calendar(3)
Impressum