1calendar(3) Erlang Module Definition calendar(3)
2
6 calendar - Local and universal time, day of the week, date and time
7 conversions.
8
10 This module provides computation of local and universal time, day of
11 the week, and many time conversion functions.
12 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 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 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 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 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 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
54 datetime() = {date(), time()}
55 datetime1970() = {{year1970(), month(), day()}, time()}
57 date() = {year(), month(), day()}
59 year() = integer() >= 0
61 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 year1970() = 1970..10000
67 month() = 1..12
69 day() = 1..31
71 time() = {hour(), minute(), second()}
73 hour() = 0..23
75 minute() = 0..59
77 second() = 0..59
79 daynum() = 1..7
81 ldom() = 28 | 29 | 30 | 31
83 yearweeknum() = {year(), weeknum()}
85 weeknum() = 1..53
87
89 date_to_gregorian_days(Date) -> Days
90 date_to_gregorian_days(Year, Month, Day) -> Days
92 Types:
94 Date = date()
96 Year = year()
97 Month = month()
98 Day = day()
99 Computes the number of gregorian days starting with year 0 and
101 ending at the specified date.
102 datetime_to_gregorian_seconds(DateTime) -> Seconds
104 Types:
106 DateTime = datetime()
108 Seconds = integer() >= 0
109 Computes the number of gregorian seconds starting with year 0
111 and ending at the specified date and time.
112 day_of_the_week(Date) -> daynum()
114 day_of_the_week(Year, Month, Day) -> daynum()
116 Types:
118 Date = date()
120 Year = year()
121 Month = month()
122 Day = day()
123 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 gregorian_days_to_date(Days) -> date()
129 Types:
131 Days = integer() >= 0
133 Computes the date from the specified number of gregorian days.
135 gregorian_seconds_to_datetime(Seconds) -> datetime()
137 Types:
139 Seconds = integer() >= 0
141 Computes the date and time from the specified number of grego‐
143 rian seconds.
144 is_leap_year(Year) -> boolean()
146 Types:
148 Year = year()
150 Checks if the specified year is a leap year.
152 iso_week_number() -> yearweeknum()
154 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 iso_week_number(Date) -> yearweeknum()
160 Types:
162 Date = date()
164 Returns tuple {Year, WeekNum} representing the ISO week number
166 for the specified date.
167 last_day_of_the_month(Year, Month) -> LastDay
169 Types:
171 Year = year()
173 Month = month()
174 LastDay = ldom()
175 Computes the number of days in a month.
177 local_time() -> datetime()
179 Returns the local time reported by the underlying operating sys‐
181 tem.
182 local_time_to_universal_time(DateTime1) -> DateTime2
184 Types:
186 DateTime1 = DateTime2 = datetime1970()
188 Converts from local time to Universal Coordinated Time (UTC).
190 DateTime1 must refer to a local date after Jan 1, 1970.
191 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 local_time_to_universal_time_dst(DateTime1) -> [DateTime]
201 Types:
203 DateTime1 = DateTime = datetime1970()
205 Converts from local time to Universal Coordinated Time (UTC).
207 DateTime1 must refer to a local date after Jan 1, 1970.
208 The return value is a list of 0, 1, or 2 possible UTC times:
210 []:
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 oc‐
215 cured).
216 [DstDateTimeUTC, DateTimeUTC]:
218 For a local {Date1, Time1} during the period that is re‐
219 peated when switching from daylight saving time, two corre‐
220 sponding UTCs exist; one for the first instance of the pe‐
221 riod when daylight saving time is still active, and one for
222 the second instance.
223 [DateTimeUTC]:
225 For all other local times only one corresponding UTC exists.
226 now_to_datetime(Now) -> datetime1970()
228 Types:
230 Now = erlang:timestamp()
232 Returns Universal Coordinated Time (UTC) converted from the re‐
234 turn value from erlang:timestamp/0.
235 now_to_local_time(Now) -> datetime1970()
237 Types:
239 Now = erlang:timestamp()
241 Returns local date and time converted from the return value from
243 erlang:timestamp/0.
244 now_to_universal_time(Now) -> datetime1970()
246 Types:
248 Now = erlang:timestamp()
250 Returns Universal Coordinated Time (UTC) converted from the re‐
252 turn value from erlang:timestamp/0.
253 rfc3339_to_system_time(DateTimeString) -> integer()
255 rfc3339_to_system_time(DateTimeString, Options) -> integer()
257 Types:
259 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 Converts an RFC 3339 timestamp into system time. The data format
268 of RFC 3339 timestamps is described by RFC 3339.
269 Valid option:
271 {unit, Unit}:
273 The time unit of the return value. The default is second.
274 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 seconds_to_daystime(Seconds) -> {Days, Time}
281 Types:
283 Seconds = Days = integer()
285 Time = time()
286 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 seconds_to_time(Seconds) -> time()
292 Types:
294 Seconds = secs_per_day()
296 secs_per_day() = 0..86400
297 Computes the time from the specified number of seconds. Seconds
299 must be less than the number of seconds per day (86400).
300 system_time_to_local_time(Time, TimeUnit) -> datetime()
302 Types:
304 Time = integer()
306 TimeUnit = erlang:time_unit()
307 Converts a specified system time into local date and time.
309 system_time_to_rfc3339(Time) -> DateTimeString
311 system_time_to_rfc3339(Time, Options) -> DateTimeString
313 Types:
315 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 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 Valid options:
333 {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 {time_designator, Character}:
342 The character used as time designator, that is, the date and
343 time separator. The default is $T.
344 {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 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 system_time_to_universal_time(Time, TimeUnit) -> datetime()
363 Types:
365 Time = integer()
367 TimeUnit = erlang:time_unit()
368 Converts a specified system time into universal date and time.
370 time_difference(T1, T2) -> {Days, Time}
372 Types:
374 T1 = T2 = datetime()
376 Days = integer()
377 Time = time()
378 Returns the difference between two {Date, Time} tuples. T2 is to
380 refer to an epoch later than T1.
381 Warning:
383 This function is obsolete. Use the conversion functions for gre‐
384 gorian days and seconds instead.
385 time_to_seconds(Time) -> secs_per_day()
388 Types:
390 Time = time()
392 secs_per_day() = 0..86400
393 Returns the number of seconds since midnight up to the specified
395 time.
396 universal_time() -> datetime()
398 Returns the Universal Coordinated Time (UTC) reported by the un‐
400 derlying operating system. Returns local time if universal time
401 is unavailable.
402 universal_time_to_local_time(DateTime) -> datetime()
404 Types:
406 DateTime = datetime1970()
408 Converts from Universal Coordinated Time (UTC) to local time.
410 DateTime must refer to a date after Jan 1, 1970.
411 valid_date(Date) -> boolean()
413 valid_date(Year, Month, Day) -> boolean()
415 Types:
417 Date = date()
419 Year = Month = Day = integer()
420 This function checks if a date is a valid.
422
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 * Y is divisible by 4, but not by 100.
429 * Y is divisible by 400.
431 Hence, 1996 is a leap year, 1900 is not, but 2000 is.
433
435 Local time is obtained from the Erlang BIF localtime/0. Universal time
436 is computed from the BIF universaltime/0.
437 The following apply:
439 * There are 86400 seconds in a day.
441 * There are 365 days in an ordinary year.
443 * There are 366 days in a leap year.
445 * There are 1461 days in a 4 year period.
447 * There are 36524 days in a 100 year period.
449 * There are 146097 days in a 400 year period.
451 * There are 719528 days between Jan 1, 0 and Jan 1, 1970.
453Ericsson AB stdlib 3.14.2.1 calendar(3)