calendar

Local and universal time, day-of-the-week, date and time conversions

This module provides computation of local and universal time, day-of-the-week, and several time conversion functions.

这个模块提供了本地时间和世界时间的计算, 星期格式日期, 和几个时间转换函数.

Time is local when it is adjusted in accordance with the current time zone and daylight saving. Time is universal when it reflects the time at longitude zero, without any adjustment for daylight saving. Universal Coordinated Time (UTC) time is also called Greenwich Mean Time (GMT).

当时间调整为当前时区和夏时制时就是本地的。当时间反映了0经度的时间而不局限于某个夏时制时就是世界时间。通用协调时间也称作格林威治标准时间。

The time functions local_time/0 and universal_time/0 provided in this module both return date and time. The reason for this is that separate functions for date and time may result in a date/time combination which is displaced by 24 hours. This happens if one of the functions is called before midnight, and the other after midnight. This problem also applies to the Erlang BIFs date/0 and time/0, and their use is strongly discouraged if a reliable date/time stamp is required.

这个模块提供的时间函数local_time/0和universal_time/0都返回日期和时间。原因是分别返回日期和时间的函数会产生日期/时间的组合，而这种组合被表示为24小时的形式。比如其中一个函数在午夜前被调用，而另一个函数在午夜后被调用，就会出现这种情况。这个问题也出现在Erlang BIFs中的data/0和time/0函数，当需要一个可靠的日期/时间戳的时候，它们的性能就会大打折扣。

All dates conform to the Gregorian calendar. This calendar was introduced by Pope Gregory XIII in 1582 and was used in all Catholic countries from this year. Protestant parts of Germany and the Netherlands adopted it in 1698, England followed in 1752, and Russia in 1918 (the October revolution of 1917 took place in November according to the Gregorian calendar).

所有的时间都是阳历的。这种日历是Pope Gregory XIII在1582年提出的，并从这年开始在所有的天主教国家使用。德国新教地区和新西兰在1698年采用，英国是在1752年，俄罗斯在1918年采用（根据阳历1917年的十月革命其实是在十一月份发生的）。

The Gregorian calendar in this module is extended back to year 0. For a given date, the gregorian days is the number of days up to and including the date specified. Similarly, the gregorian seconds for a given date and time, is the the number of seconds up to and including the specified date and time.

阳历在这个模块里是从元年开始的。对于一个给定的日期，阳历天数是到这天并包括这天在内的数目。同样的，对于一个给定日期和时间的阳历秒，是到这个日期的并包括这个日期在内的秒数。

For computing differences between epochs in time, use the functions counting gregorian days or seconds. If epochs are given as local time, they must be converted to universal time, in order to get the correct value of the elapsed time between epochs. Use of the function time_difference/2 is discouraged.

为了计算不同时间点在时间上的不同，使用函数来计数阳历天数而或者秒数。如果时间点是以当地时间的形式给出，为了得出在这些时间点之间的准确时间值，必须将它们转化成通用时间的形式。使用函数time_difference/2效果不好。

There exists different definitions for the week of the year. The calendar module contains a week of the year implementation which conforms to the ISO 8601 standard. Since the week number for a given date can fall on the previous, the current or on the next year it is important to provide the information which year is it together with the week number. The function iso_week_number/0 and iso_week_number/1 returns a tuple of the year and the week number.

对于星期的定义有多种。日历模块包含着一个符合ISO8601标准的星期的实现。因为对于一个给定日期的星期数可能坐落在上年、今年或者下年，所以在给出星期数的同时提供年份的信息显得十分的重要。 iso_week_number/0 函数和iso_week_number/1函数返回年份和星期的元组。

Year cannot be abbreviated. Example: 93 denotes year 93, not 1993. Valid range depends on the underlying OS. The date tuple must denote a valid date.

年份不能缩写。比如：93代表93年，而不是1993年。合法的范围取决于底层的操作系统。日期元组必须代表一个合法的日期。

Functions:

date_to_gregorian_days(Date) -> Days

Date = date(),
Days = non_neg_integer()

date_to_gregorian_days(Year, Month, Day) -> Days

Year = year(),
Month = month(),
Day = day(),
Days = non_neg_integer()

This function computes the number of gregorian days starting with year 0 and ending at the given date.

datetime_to_gregorian_seconds(DateTime) -> Seconds

DateTime = datetime(),
Seconds = non_neg_integer()

This function computes the number of gregorian seconds starting with year 0 and ending at the given date and time.

day_of_the_week(Date) -> daynum()

Date= date()

day_of_the_week(Year, Month, Day) -> daynum()

Year = year(),
Month = month(),
Day = day()

This function computes the day of the week given Year, Month and Day. The return value denotes the day of the week as 1: Monday, 2: Tuesday, and so on.

gregorian_days_to_date(Days) -> date()

Days = non_neg_integer()

This function computes the date given the number of gregorian days.

gregorian_seconds_to_datetime(Seconds) -> datetime()

Seconds = non_neg_integer()

This function computes the date and time from the given number of gregorian seconds.

is_leap_year(Year) -> boolean()

Year = year()

This function checks if a year is a leap year.

iso_week_number() -> yearweeknum()

This function returns the tuple {Year, WeekNum} representing the iso week number for the actual date. For determining the actual date, the function local_time/0 is used.

iso_week_number(Date) -> yearweeknum()

Date = date()

This function returns the tuple {Year, WeekNum} representing the iso week number for the given date.

last_day_of_the_month(Year, Month) -> LastDay

Year = year(),
Month = month(),
LastDay = ldom()

This function computes the number of days in a month.

local_time() -> datetime()

This function returns the local time reported by the underlying operating system.

local_time_to_universal_time(DateTime1) -> DateTime2

DateTime1 = datetime1970(),
DateTime2 = datetime1970()

This function converts from local time to Universal Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.

Warning:

This function is deprecated. Use local_time_to_universal_time_dst/1 instead, as it gives a more correct and complete result. Especially for the period that does not exist since it gets skipped during the switch to daylight saving time, this function still returns a result.

local_time_to_universal_time_dst(DateTime1) -> [DateTime]

DateTime1 = datetime1970(),
DateTime = datetime1970()

This function converts from local time to Universal Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.

The return value is a list of 0, 1 or 2 possible UTC times:

now_to_local_time(Now) -> datetime1970()

Now = erlang:timestamp()

This function returns local date and time converted from the return value from erlang:now().

now_to_universal_time(Now) -> datetime1970()

Now = erlang:timestamp()

now_to_datetime(Now) -> datetime1970()

Now = erlang:timestamp()

This function returns Universal Coordinated Time (UTC) converted from the return value from erlang:now().

seconds_to_daystime(Seconds) -> {Days, Time}

Seconds = integer(),
Days = integer(),
Time = time()

This function transforms a given number of seconds into days, hours, minutes, and seconds. The Time part is always non-negative, but Days is negative if the argument Seconds is.

seconds_to_time(Seconds) -> time()

Seconds = secs_per_day()

This function computes the time from the given number of seconds. Seconds must be less than the number of seconds per day (86400).

time_difference(T1, T2) -> {Days, Time}

T1 = datetime(),
T2 = datetime(),
Days = integer(),
Time = time()

This function returns the difference between two {Date, Time} tuples. T2 should refer to an epoch later than T1.

Warning:

This function is obsolete. Use the conversion functions for gregorian days and seconds instead.

time_to_seconds(Time) -> secs_per_day()

Time = time()

This function computes the number of seconds since midnight up to the specified time.

universal_time() -> datetime()

This function returns the Universal Coordinated Time (UTC) reported by the underlying operating system. Local time is returned if universal time is not available.

universal_time_to_local_time(DateTime) -> datetime()

DateTime = datetime1970()

This function converts from Universal Coordinated Time (UTC) to local time. DateTime must refer to a date after Jan 1, 1970.

valid_date(Date) -> boolean()

Date = date()

valid_date(Year, Month, Day) -> boolean()

Year = integer(),
Month = integer(),
Day = integer()

This function checks if a date is a valid.

Leap Years

The notion that every fourth year is a leap year is not completely true. By the Gregorian rule, a year Y is a leap year if either of the following rules is valid:

Y is divisible by 4, but not by 100; or

Y is divisible by 400.

Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.

Date and Time Source

Local time is obtained from the Erlang BIF localtime/0. Universal time is computed from the BIF universaltime/0.

The following facts apply:

there are 86400 seconds in a day

there are 365 days in an ordinary year

there are 366 days in a leap year

there are 1461 days in a 4 year period

there are 36524 days in a 100 year period

there are 146097 days in a 400 year period

there are 719528 days between Jan 1, 0 and Jan 1, 1970.