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 rfc3339_time_unit() =
89 microsecond | millisecond | nanosecond | second | native
90 Note:
92 The native time unit was added to rfc3339_time_unit() in OTP
93 25.0.
94
97 date_to_gregorian_days(Date) -> Days
98 date_to_gregorian_days(Year, Month, Day) -> Days
100 Types:
102 Date = date()
104 Year = year()
105 Month = month()
106 Day = day()
107 Computes the number of gregorian days starting with year 0 and
109 ending at the specified date.
110 datetime_to_gregorian_seconds(DateTime) -> Seconds
112 Types:
114 DateTime = datetime()
116 Seconds = integer() >= 0
117 Computes the number of gregorian seconds starting with year 0
119 and ending at the specified date and time.
120 day_of_the_week(Date) -> daynum()
122 day_of_the_week(Year, Month, Day) -> daynum()
124 Types:
126 Date = date()
128 Year = year()
129 Month = month()
130 Day = day()
131 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 gregorian_days_to_date(Days) -> date()
137 Types:
139 Days = integer() >= 0
141 Computes the date from the specified number of gregorian days.
143 gregorian_seconds_to_datetime(Seconds) -> datetime()
145 Types:
147 Seconds = integer() >= 0
149 Computes the date and time from the specified number of grego‐
151 rian seconds.
152 is_leap_year(Year) -> boolean()
154 Types:
156 Year = year()
158 Checks if the specified year is a leap year.
160 iso_week_number() -> yearweeknum()
162 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 iso_week_number(Date) -> yearweeknum()
168 Types:
170 Date = date()
172 Returns tuple {Year, WeekNum} representing the ISO week number
174 for the specified date.
175 last_day_of_the_month(Year, Month) -> LastDay
177 Types:
179 Year = year()
181 Month = month()
182 LastDay = ldom()
183 Computes the number of days in a month.
185 local_time() -> datetime()
187 Returns the local time reported by the underlying operating sys‐
189 tem.
190 local_time_to_universal_time(DateTime1) -> DateTime2
192 Types:
194 DateTime1 = DateTime2 = datetime1970()
196 Converts from local time to Universal Coordinated Time (UTC).
198 DateTime1 must refer to a local date after Jan 1, 1970.
199 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 local_time_to_universal_time_dst(DateTime1) -> [DateTime]
209 Types:
211 DateTime1 = DateTime = datetime1970()
213 Converts from local time to Universal Coordinated Time (UTC).
215 DateTime1 must refer to a local date after Jan 1, 1970.
216 The return value is a list of 0, 1, or 2 possible UTC times:
218 []:
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 [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 [DateTimeUTC]:
233 For all other local times only one corresponding UTC exists.
234 now_to_datetime(Now) -> datetime1970()
236 Types:
238 Now = erlang:timestamp()
240 Returns Universal Coordinated Time (UTC) converted from the re‐
242 turn value from erlang:timestamp/0.
243 now_to_local_time(Now) -> datetime1970()
245 Types:
247 Now = erlang:timestamp()
249 Returns local date and time converted from the return value from
251 erlang:timestamp/0.
252 now_to_universal_time(Now) -> datetime1970()
254 Types:
256 Now = erlang:timestamp()
258 Returns Universal Coordinated Time (UTC) converted from the re‐
260 turn value from erlang:timestamp/0.
261 rfc3339_to_system_time(DateTimeString) -> integer()
263 rfc3339_to_system_time(DateTimeString, Options) -> integer()
265 Types:
267 DateTimeString = rfc3339_string()
269 Options = [Option]
270 Option = {unit, rfc3339_time_unit()}
271 rfc3339_string() = [byte(), ...]
272 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 Valid option:
278 {unit, Unit}:
280 The time unit of the return value. The default is second.
281 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 seconds_to_daystime(Seconds) -> {Days, Time}
288 Types:
290 Seconds = Days = integer()
292 Time = time()
293 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 seconds_to_time(Seconds) -> time()
299 Types:
301 Seconds = secs_per_day()
303 secs_per_day() = 0..86400
304 Computes the time from the specified number of seconds. Seconds
306 must be less than the number of seconds per day (86400).
307 system_time_to_local_time(Time, TimeUnit) -> datetime()
309 Types:
311 Time = integer()
313 TimeUnit = erlang:time_unit()
314 Converts a specified system time into local date and time.
316 system_time_to_rfc3339(Time) -> DateTimeString
318 system_time_to_rfc3339(Time, Options) -> DateTimeString
320 Types:
322 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 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 Valid options:
338 {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 {time_designator, Character}:
347 The character used as time designator, that is, the date and
348 time separator. The default is $T.
349 {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 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 system_time_to_universal_time(Time, TimeUnit) -> datetime()
369 Types:
371 Time = integer()
373 TimeUnit = erlang:time_unit()
374 Converts a specified system time into universal date and time.
376 time_difference(T1, T2) -> {Days, Time}
378 Types:
380 T1 = T2 = datetime()
382 Days = integer()
383 Time = time()
384 Returns the difference between two {Date, Time} tuples. T2 is to
386 refer to an epoch later than T1.
387 Warning:
389 This function is obsolete. Use the conversion functions for gre‐
390 gorian days and seconds instead.
391 time_to_seconds(Time) -> secs_per_day()
394 Types:
396 Time = time()
398 secs_per_day() = 0..86400
399 Returns the number of seconds since midnight up to the specified
401 time.
402 universal_time() -> datetime()
404 Returns the Universal Coordinated Time (UTC) reported by the un‐
406 derlying operating system. Returns local time if universal time
407 is unavailable.
408 universal_time_to_local_time(DateTime) -> datetime()
410 Types:
412 DateTime = datetime1970()
414 Converts from Universal Coordinated Time (UTC) to local time.
416 DateTime must refer to a date after Jan 1, 1970.
417 valid_date(Date) -> boolean()
419 valid_date(Year, Month, Day) -> boolean()
421 Types:
423 Date = date()
425 Year = Month = Day = integer()
426 This function checks if a date is a valid.
428
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 * Y is divisible by 4, but not by 100.
435 * Y is divisible by 400.
437 Hence, 1996 is a leap year, 1900 is not, but 2000 is.
439
441 Local time is obtained from the Erlang BIF localtime/0. Universal time
442 is computed from the BIF universaltime/0.
443 The following apply:
445 * There are 86400 seconds in a day.
447 * There are 365 days in an ordinary year.
449 * There are 366 days in a leap year.
451 * There are 1461 days in a 4 year period.
453 * There are 36524 days in a 100 year period.
455 * There are 146097 days in a 400 year period.
457 * There are 719528 days between Jan 1, 0 and Jan 1, 1970.
459Ericsson AB stdlib 4.3.1.3 calendar(3)