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. This 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 re‐
25       liable 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
88       rfc3339_time_unit() =
89           microsecond | millisecond | nanosecond | second | native
90
91          Note:
92              The native time unit was added  to  rfc3339_time_unit()  in  OTP
93              25.0.
94
95

EXPORTS

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

LEAP YEARS

430       The notion that every fourth year is a  leap  year  is  not  completely
431       true. By the Gregorian rule, a year Y is a leap year if one of the fol‐
432       lowing rules is valid:
433
434         * Y is divisible by 4, but not by 100.
435
436         * Y is divisible by 400.
437
438       Hence, 1996 is a leap year, 1900 is not, but 2000 is.
439

DATE AND TIME SOURCE

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