From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/calendar.xml | 377 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 377 insertions(+) create mode 100644 lib/stdlib/doc/src/calendar.xml (limited to 'lib/stdlib/doc/src/calendar.xml') diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml new file mode 100644 index 0000000000..36f0c03162 --- /dev/null +++ b/lib/stdlib/doc/src/calendar.xml @@ -0,0 +1,377 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + calendar + Peter Högfeldt + + 1996-11-05 + B +
+ 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).

+

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.

+

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).

+

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.

+ + +
+ DATA TYPES + +date() = {Year, Month, Day} + Year = int() + Month = 1..12 + Day = 1..31 +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. + +time() = {Hour, Minute, Second} + Hour = 0..23 + Minute = Second = 0..59 +
+ + + date_to_gregorian_days(Date) -> Days + date_to_gregorian_days(Year, Month, Day) -> Days + Compute the number of days from year 0 up to the given date + + Date = date() + Days = int() + + +

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

+ + + + datetime_to_gregorian_seconds({Date, Time}) -> Seconds + Compute the number of seconds from year 0 up to the given date and time + + Date = date() + Time = time() + Seconds = int() + + +

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) -> DayNumber + day_of_the_week(Year, Month, Day) -> DayNumber + Compute the day of the week + + Date = date() + DayNumber = 1..7 + + +

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 + Compute the date given the number of gregorian days + + Days = int() + Date = date() + + +

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

+ + + + gregorian_seconds_to_datetime(Seconds) -> {Date, Time} + Compute the date given the number of gregorian days + + Seconds = int() + Date = date() + Time = time() + + +

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

+ + + + is_leap_year(Year) -> bool() + Check if a year is a leap year + +

This function checks if a year is a leap year.

+ + + + last_day_of_the_month(Year, Month) -> int() + Compute the number of days in a month + +

This function computes the number of days in a month.

+ + + + local_time() -> {Date, Time} + Compute local time + + Date = date() + Time = time() + + +

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

+ + + + local_time_to_universal_time({Date1, Time1}) -> {Date2, Time2} + Convert from local time to universal time (deprecated) + +

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

+ +

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({Date1, Time1}) -> [{Date, Time}] + Convert from local time to universal time(s) + + Date1 = Date = date() + Time1 = Time = time() + + +

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

+

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

+ + [] + +

For a local {Date1, Time1} during the period that + is skipped when switching to daylight saving + time, there is no corresponding UTC since the local time + is illegal - it has never happened.

+ + [DstDateTimeUTC, DateTimeUTC] + +

For a local {Date1, Time1} during the period that + is repeated when switching from daylight saving + time, there are two corresponding UTCs. One for the first + instance of the period when daylight saving time is still + active, and one for the second instance.

+ + [DateTimeUTC] + +

For all other local times there is only one + corresponding UTC.

+ + + + + + now_to_local_time(Now) -> {Date, Time} + Convert now to local date and time + + Now -- see erlang:now/0 + Date = date() + Time = time() + + +

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

+ + + + now_to_universal_time(Now) -> {Date, Time} + now_to_datetime(Now) -> {Date, Time} + Convert now to date and time + + Now -- see erlang:now/0 + Date = date() + Time = time() + + +

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

+ + + + seconds_to_daystime(Seconds) -> {Days, Time} + Compute days and time from seconds + + Seconds = Days = int() + 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 + Compute time from seconds + + Seconds = int() < 86400 + Time = time() + + +

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} + Compute the difference between two times (deprecated) + +

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

+ +

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

+ + + + + time_to_seconds(Time) -> Seconds + Compute the number of seconds since midnight up to the given time + + Time = time() + Seconds = int() + + +

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

+ + + + universal_time() -> {Date, Time} + Compute universal time + + Date = date() + Time = time() + + +

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({Date1, Time1}) -> {Date2, Time2} + Convert from universal time to local time + + Date1 = Date2 = date() + Time1 = Time2 = time() + + +

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

+ + + + valid_date(Date) -> bool() + valid_date(Year, Month, Day) -> bool() + Check if a date is valid + + Date = date() + + +

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. + +
+ + -- cgit v1.2.3