diff options
Diffstat (limited to 'lib/stdlib/doc/src/calendar.xml')
| -rw-r--r-- | lib/stdlib/doc/src/calendar.xml | 248 |
1 files changed, 144 insertions, 104 deletions
diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index 38bf55679e..65b3edcdf6 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -29,20 +29,21 @@ <rev>B</rev> </header> <module>calendar</module> - <modulesummary>Local and universal time, day-of-the-week, date and time conversions</modulesummary> + <modulesummary>Local and universal time, day of the week, date and time + conversions.</modulesummary> <description> <p>This module provides computation of local and universal time, - day-of-the-week, and several time conversion functions.</p> + day of the week, and many time conversion functions.</p> <p>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).</p> <p>The time functions <c>local_time/0</c> and - <c>universal_time/0</c> 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 + <c>universal_time/0</c> in this module both return date + and time. The is because separate functions for date + and time can result in a date/time combination that is displaced + by 24 hours. This occurs if one of the functions is called before midnight, and the other after midnight. This problem also applies to the Erlang BIFs <c>date/0</c> and <c>time/0</c>, and their use is strongly discouraged if a reliable date/time stamp @@ -56,22 +57,21 @@ <p>The Gregorian calendar in this module is extended back to year 0. For a given date, the <em>gregorian days</em> is the number of days up to and including the date specified. Similarly, - the <em>gregorian seconds</em> for a given date and time, is - the the number of seconds up to and including the specified date + the <em>gregorian seconds</em> for a specified date and time is + the number of seconds up to and including the specified date and time.</p> <p>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 <c>time_difference/2</c> is discouraged.</p> - <p>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 <c>iso_week_number/0</c> - and <c>iso_week_number/1</c> returns a tuple of the year and the - week number.</p> + specified as local time, they must be converted to universal time + to get the correct value of the elapsed time between epochs. + Use of function <c>time_difference/2</c> is discouraged.</p> + <p>Different definitions exist for the week of the year. + This module contains a week of the year implementation + conforming to the ISO 8601 standard. As the week number for a + specified date can fall on the previous, the current, or on the next + year, it is important to specify both the year and the week number. + Functions <c>iso_week_number/0</c> and <c>iso_week_number/1</c> + return a tuple of the year and the week number.</p> </description> <datatypes> @@ -86,9 +86,9 @@ </datatype> <datatype> <name name="year"/> - <desc><p>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.</p> + <desc><p>Year cannot be abbreviated. For example, 93 denotes year + 93, not 1993. The valid range depends on the underlying operating + system. The date tuple must denote a valid date.</p> </desc> </datatype> <datatype> @@ -130,186 +130,221 @@ <func> <name name="date_to_gregorian_days" arity="1"/> <name name="date_to_gregorian_days" arity="3"/> - <fsummary>Compute the number of days from year 0 up to the given date</fsummary> + <fsummary>Compute the number of days from year 0 up to the specified + date.</fsummary> <type variable="Date" name_i="1"/> <type variable="Year"/> <type variable="Month"/> <type variable="Day"/> <desc> - <p>This function computes the number of gregorian days starting - with year 0 and ending at the given date.</p> + <p>Computes the number of gregorian days starting + with year 0 and ending at the specified date.</p> </desc> </func> + <func> <name name="datetime_to_gregorian_seconds" arity="1"/> - <fsummary>Compute the number of seconds from year 0 up to the given date and time</fsummary> + <fsummary>Compute the number of seconds from year 0 up to the specified + date and time.</fsummary> <desc> - <p>This function computes the number of gregorian seconds - starting with year 0 and ending at the given date and time.</p> + <p>Computes the number of gregorian seconds starting + with year 0 and ending at the specified date and time.</p> </desc> </func> + <func> <name name="day_of_the_week" arity="1"/> <name name="day_of_the_week" arity="3"/> - <fsummary>Compute the day of the week</fsummary> + <fsummary>Compute the day of the week.</fsummary> <type variable="Date" name_i="1"/> <type variable="Year"/> <type variable="Month"/> <type variable="Day"/> <desc> - <p>This function computes the day of the week given <c><anno>Year</anno></c>, - <c><anno>Month</anno></c> and <c><anno>Day</anno></c>. The return value denotes the day - of the week as <c>1</c>: Monday, <c>2</c>: Tuesday, and so on.</p> + <p>Computes the day of the week from the specified + <c><anno>Year</anno></c>, <c><anno>Month</anno></c>, and + <c><anno>Day</anno></c>. Returns the day of the week as + <c>1</c>: Monday, <c>2</c>: Tuesday, and so on.</p> </desc> </func> + <func> <name name="gregorian_days_to_date" arity="1"/> - <fsummary>Compute the date given the number of gregorian days</fsummary> + <fsummary>Compute the date from the number of gregorian days.</fsummary> <desc> - <p>This function computes the date given the number of - gregorian days.</p> + <p>Computes the date from the specified number of gregorian days.</p> </desc> </func> + <func> <name name="gregorian_seconds_to_datetime" arity="1"/> - <fsummary>Compute the date given the number of gregorian days</fsummary> + <fsummary>Compute the date and time from the number of gregorian seconds. + </fsummary> <desc> - <p>This function computes the date and time from the given + <p>Computes the date and time from the specified number of gregorian seconds.</p> </desc> </func> + <func> <name name="is_leap_year" arity="1"/> - <fsummary>Check if a year is a leap year</fsummary> + <fsummary>Check if the year is a leap year.</fsummary> <desc> - <p>This function checks if a year is a leap year.</p> + <p>Checks if the specified year is a leap year.</p> </desc> </func> + <func> <name name="iso_week_number" arity="0"/> - <fsummary>Compute the iso week number for the actual date</fsummary> + <fsummary>Compute the ISO week number for the actual date.</fsummary> <desc> - <p>This function returns the tuple {Year, WeekNum} representing - the iso week number for the actual date. For determining the - actual date, the function <c>local_time/0</c> is used.</p> + <p>Returns tuple <c>{Year, WeekNum}</c> representing + the ISO week number for the actual date. To determine the + actual date, use function + <seealso marker="#local_time/0"><c>local_time/0</c></seealso>.</p> </desc> </func> + <func> <name name="iso_week_number" arity="1"/> - <fsummary>Compute the iso week number for the given date</fsummary> + <fsummary>Compute the ISO week number for the specified date.</fsummary> <desc> - <p>This function returns the tuple {Year, WeekNum} representing - the iso week number for the given date.</p> + <p>Returns tuple <c>{Year, WeekNum}</c> representing + the ISO week number for the specified date.</p> </desc> </func> + <func> <name name="last_day_of_the_month" arity="2"/> - <fsummary>Compute the number of days in a month</fsummary> + <fsummary>Compute the number of days in a month.</fsummary> <desc> - <p>This function computes the number of days in a month.</p> + <p>Computes the number of days in a month.</p> </desc> </func> + <func> <name name="local_time" arity="0"/> - <fsummary>Compute local time</fsummary> + <fsummary>Compute local time.</fsummary> <desc> - <p>This function returns the local time reported by + <p>Returns the local time reported by the underlying operating system.</p> </desc> </func> + <func> <name name="local_time_to_universal_time" arity="1"/> - <fsummary>Convert from local time to universal time (deprecated)</fsummary> + <fsummary>Convert from local time to universal time (deprecated). + </fsummary> <desc> - <p>This function converts from local time to Universal - Coordinated Time (UTC). <c><anno>DateTime1</anno></c> must refer to a local + <p>Converts from local time to Universal Coordinated Time (UTC). + <c><anno>DateTime1</anno></c> must refer to a local date after Jan 1, 1970.</p> <warning> <p>This function is deprecated. Use - <c>local_time_to_universal_time_dst/1</c> instead, as it - gives a more correct and complete result. Especially for - the period that does not exist since it gets skipped during + <seealso marker="#local_time_to_universal_time_dst/1"> + <c>local_time_to_universal_time_dst/1</c></seealso> + instead, as it gives a more correct and complete result. + Especially for + the period that does not exist, as it is skipped during the switch <em>to</em> daylight saving time, this function still returns a result.</p> </warning> </desc> </func> + <func> <name name="local_time_to_universal_time_dst" arity="1"/> - <fsummary>Convert from local time to universal time(s)</fsummary> + <fsummary>Convert from local time to universal time(s).</fsummary> <desc> - <p>This function converts from local time to Universal - Coordinated Time (UTC). <c><anno>DateTime1</anno></c> must refer to a local + <p>Converts from local time to Universal Coordinated Time (UTC). + <c><anno>DateTime1</anno></c> must refer to a local date after Jan 1, 1970.</p> - <p>The return value is a list of 0, 1 or 2 possible UTC times:</p> + <p>The return value is a list of 0, 1, or 2 possible UTC times:</p> <taglist> <tag><c>[]</c></tag> <item> <p>For a local <c>{Date1, Time1}</c> during the period that is skipped when switching <em>to</em> daylight saving - time, there is no corresponding UTC since the local time - is illegal - it has never happened.</p> + time, there is no corresponding UTC, as the local time + is illegal (it has never occured).</p> </item> <tag><c>[DstDateTimeUTC, DateTimeUTC]</c></tag> <item> <p>For a local <c>{Date1, Time1}</c> during the period that is repeated when switching <em>from</em> daylight saving - time, there are two corresponding UTCs. One for the first + time, two corresponding UTCs exist; one for the first instance of the period when daylight saving time is still active, and one for the second instance.</p> </item> <tag><c>[DateTimeUTC]</c></tag> <item> - <p>For all other local times there is only one - corresponding UTC.</p> + <p>For all other local times only one corresponding UTC exists.</p> </item> </taglist> </desc> </func> + + <func> + <name name="now_to_datetime" arity="1"/> + <fsummary>Convert now to date and time.</fsummary> + <desc> + <p>Returns Universal Coordinated Time (UTC) + converted from the return value from + <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + </p> + </desc> + </func> + <func> <name name="now_to_local_time" arity="1"/> - <fsummary>Convert now to local date and time</fsummary> + <fsummary>Convert now to local date and time.</fsummary> <desc> - <p>This function returns local date and time converted from - the return value from - <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>.</p> + <p>Returns local date and time converted from the return value from + <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + </p> </desc> </func> + <func> <name name="now_to_universal_time" arity="1"/> - <name name="now_to_datetime" arity="1"/> - <fsummary>Convert now to date and time</fsummary> + <fsummary>Convert now to date and time.</fsummary> <desc> - <p>This function returns Universal Coordinated Time (UTC) - converted from the return value from - <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>.</p> + <p>Returns Universal Coordinated Time (UTC) + converted from the return value from + <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + </p> </desc> </func> + <func> <name name="seconds_to_daystime" arity="1"/> - <fsummary>Compute days and time from seconds</fsummary> + <fsummary>Compute days and time from seconds.</fsummary> <desc> - <p>This function transforms a given number of seconds into days, - hours, minutes, and seconds. The <c><anno>Time</anno></c> part is always - non-negative, but <c><anno>Days</anno></c> is negative if the argument + <p>Converts a specified number of seconds into days, hours, minutes, + and seconds. <c><anno>Time</anno></c> is always non-negative, but + <c><anno>Days</anno></c> is negative if argument <c><anno>Seconds</anno></c> is.</p> </desc> </func> + <func> <name name="seconds_to_time" arity="1"/> - <fsummary>Compute time from seconds</fsummary> + <fsummary>Compute time from seconds.</fsummary> <type name="secs_per_day"/> <desc> - <p>This function computes the time from the given number of - seconds. <c><anno>Seconds</anno></c> must be less than the number of + <p>Computes the time from the specified number of seconds. + <c><anno>Seconds</anno></c> must be less than the number of seconds per day (86400).</p> </desc> </func> + <func> <name name="time_difference" arity="2"/> - <fsummary>Compute the difference between two times (deprecated)</fsummary> + <fsummary>Compute the difference between two times (deprecated). + </fsummary> <desc> - <p>This function returns the difference between two <c>{Date, Time}</c> tuples. <c><anno>T2</anno></c> should refer to an epoch later + <p>Returns the difference between two <c>{Date, Time}</c> tuples. + <c><anno>T2</anno></c> is to refer to an epoch later than <c><anno>T1</anno></c>.</p> <warning> <p>This function is obsolete. Use the conversion functions for @@ -317,33 +352,38 @@ </warning> </desc> </func> + <func> <name name="time_to_seconds" arity="1"/> - <fsummary>Compute the number of seconds since midnight up to the given time</fsummary> + <fsummary>Compute the number of seconds since midnight up to the + specified time.</fsummary> <type name="secs_per_day"/> <desc> - <p>This function computes the number of seconds since midnight + <p>Returns the number of seconds since midnight up to the specified time.</p> </desc> </func> + <func> <name name="universal_time" arity="0"/> - <fsummary>Compute universal time</fsummary> + <fsummary>Compute universal time.</fsummary> <desc> - <p>This function returns the Universal Coordinated Time (UTC) - reported by the underlying operating system. Local time is - returned if universal time is not available.</p> + <p>Returns the Universal Coordinated Time (UTC) + reported by the underlying operating system. Returns local time if + universal time is unavailable.</p> </desc> </func> + <func> <name name="universal_time_to_local_time" arity="1"/> - <fsummary>Convert from universal time to local time</fsummary> + <fsummary>Convert from universal time to local time.</fsummary> <desc> - <p>This function converts from Universal Coordinated Time (UTC) - to local time. <c><anno>DateTime</anno></c> must refer to a date after Jan 1, - 1970.</p> + <p>Converts from Universal Coordinated Time (UTC) to local time. + <c><anno>DateTime</anno></c> must refer to a date after Jan 1, 1970. + </p> </desc> </func> + <func> <name name="valid_date" arity="1"/> <name name="valid_date" arity="3"/> @@ -362,31 +402,31 @@ <title>Leap Years</title> <p>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:</p> + one of the following rules is valid:</p> <list type="bulleted"> <item> - <p>Y is divisible by 4, but not by 100; or</p> + <p>Y is divisible by 4, but not by 100.</p> </item> <item> <p>Y is divisible by 400.</p> </item> </list> - <p>Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.</p> + <p>Hence, 1996 is a leap year, 1900 is not, but 2000 is.</p> </section> <section> <title>Date and Time Source</title> <p>Local time is obtained from the Erlang BIF <c>localtime/0</c>. Universal time is computed from the BIF <c>universaltime/0</c>.</p> - <p>The following facts apply:</p> + <p>The following fapply:</p> <list type="bulleted"> - <item>there are 86400 seconds in a day</item> - <item>there are 365 days in an ordinary year</item> - <item>there are 366 days in a leap year</item> - <item>there are 1461 days in a 4 year period</item> - <item>there are 36524 days in a 100 year period</item> - <item>there are 146097 days in a 400 year period</item> - <item>there are 719528 days between Jan 1, 0 and Jan 1, 1970.</item> + <item>There are 86400 seconds in a day.</item> + <item>There are 365 days in an ordinary year.</item> + <item>There are 366 days in a leap year.</item> + <item>There are 1461 days in a 4 year period.</item> + <item>There are 36524 days in a 100 year period.</item> + <item>There are 146097 days in a 400 year period.</item> + <item>There are 719528 days between Jan 1, 0 and Jan 1, 1970.</item> </list> </section> </erlref> |