aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--man/calc.texi84
1 files changed, 42 insertions, 42 deletions
diff --git a/man/calc.texi b/man/calc.texi
index ca7167905cb..d927346ff6b 100644
--- a/man/calc.texi
+++ b/man/calc.texi
@@ -17364,31 +17364,31 @@ business day.
17364 17364
17365@noindent 17365@noindent
17366@cindex Time zones 17366@cindex Time zones
17367@cindex Daylight savings time 17367@cindex Daylight saving time
17368Time zones and daylight savings time are a complicated business. 17368Time zones and daylight saving time are a complicated business.
17369The conversions to and from Julian and Unix-style dates automatically 17369The conversions to and from Julian and Unix-style dates automatically
17370compute the correct time zone and daylight savings adjustment to use, 17370compute the correct time zone and daylight saving adjustment to use,
17371provided they can figure out this information. This section describes 17371provided they can figure out this information. This section describes
17372Calc's time zone adjustment algorithm in detail, in case you want to 17372Calc's time zone adjustment algorithm in detail, in case you want to
17373do conversions in different time zones or in case Calc's algorithms 17373do conversions in different time zones or in case Calc's algorithms
17374can't determine the right correction to use. 17374can't determine the right correction to use.
17375 17375
17376Adjustments for time zones and daylight savings time are done by 17376Adjustments for time zones and daylight saving time are done by
17377@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other 17377@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other
17378commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates 17378commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates
17379to exactly 30 days even though there is a daylight-savings 17379to exactly 30 days even though there is a daylight-saving
17380transition in between. This is also true for Julian pure dates: 17380transition in between. This is also true for Julian pure dates:
17381@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian 17381@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian
17382and Unix date/times will adjust for daylight savings time: 17382and Unix date/times will adjust for daylight saving time:
17383@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} 17383@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)}
17384evaluates to @samp{29.95834} (that's 29 days and 23 hours) 17384evaluates to @samp{29.95834} (that's 29 days and 23 hours)
17385because one hour was lost when daylight savings commenced on 17385because one hour was lost when daylight saving commenced on
17386April 7, 1991. 17386April 7, 1991.
17387 17387
17388In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} 17388In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})}
17389computes the actual number of 24-hour periods between two dates, whereas 17389computes the actual number of 24-hour periods between two dates, whereas
17390@samp{@var{date1} - @var{date2}} computes the number of calendar 17390@samp{@var{date1} - @var{date2}} computes the number of calendar
17391days between two dates without taking daylight savings into account. 17391days between two dates without taking daylight saving into account.
17392 17392
17393@pindex calc-time-zone 17393@pindex calc-time-zone
17394@ignore 17394@ignore
@@ -17400,7 +17400,7 @@ zone specified by its numeric prefix argument into a number of
17400seconds difference from Greenwich mean time (GMT). If the argument 17400seconds difference from Greenwich mean time (GMT). If the argument
17401is a number, the result is simply that value multiplied by 3600. 17401is a number, the result is simply that value multiplied by 3600.
17402Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If 17402Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If
17403Daylight Savings time is in effect, one hour should be subtracted from 17403Daylight Saving time is in effect, one hour should be subtracted from
17404the normal difference. 17404the normal difference.
17405 17405
17406If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other 17406If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other
@@ -17411,12 +17411,12 @@ stack position.) This allows you to give a non-integer time zone
17411adjustment. The time-zone argument can also be an HMS form, or 17411adjustment. The time-zone argument can also be an HMS form, or
17412it can be a variable which is a time zone name in upper- or lower-case. 17412it can be a variable which is a time zone name in upper- or lower-case.
17413For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} 17413For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
17414(for Pacific standard and daylight savings times, respectively). 17414(for Pacific standard and daylight saving times, respectively).
17415 17415
17416North American and European time zone names are defined as follows; 17416North American and European time zone names are defined as follows;
17417note that for each time zone there is one name for standard time, 17417note that for each time zone there is one name for standard time,
17418another for daylight savings time, and a third for ``generalized'' time 17418another for daylight saving time, and a third for ``generalized'' time
17419in which the daylight savings adjustment is computed from context. 17419in which the daylight saving adjustment is computed from context.
17420 17420
17421@smallexample 17421@smallexample
17422@group 17422@group
@@ -17441,7 +17441,7 @@ Pacific Time look like this:
17441@smallexample 17441@smallexample
17442@group 17442@group
17443( ( "PST" 8 0 ) ; Name as an upper-case string, then standard 17443( ( "PST" 8 0 ) ; Name as an upper-case string, then standard
17444 ( "PDT" 8 -1 ) ; adjustment, then daylight savings adjustment. 17444 ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment.
17445 ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. 17445 ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone.
17446@end group 17446@end group
17447@end smallexample 17447@end smallexample
@@ -17464,10 +17464,10 @@ i.e., it uses the local time zone as obtained from the @code{date}
17464command. 17464command.
17465 17465
17466If the time zone name found is one of the standard or daylight 17466If the time zone name found is one of the standard or daylight
17467savings zone names from the above table, and Calc's internal 17467saving zone names from the above table, and Calc's internal
17468daylight savings algorithm says that time and zone are consistent 17468daylight saving algorithm says that time and zone are consistent
17469(e.g., @code{PDT} accompanies a date that Calc's algorithm would also 17469(e.g., @code{PDT} accompanies a date that Calc's algorithm would also
17470consider to be daylight savings, or @code{PST} accompanies a date 17470consider to be daylight saving, or @code{PST} accompanies a date
17471that Calc would consider to be standard time), then Calc substitutes 17471that Calc would consider to be standard time), then Calc substitutes
17472the corresponding generalized time zone (like @code{PGT}). 17472the corresponding generalized time zone (like @code{PGT}).
17473 17473
@@ -17484,38 +17484,38 @@ The @kbd{t J} and @code{t U} commands with no numeric prefix
17484arguments do the same thing as @samp{tzone()}. If the current 17484arguments do the same thing as @samp{tzone()}. If the current
17485time zone is a generalized time zone, e.g., @code{EGT}, Calc 17485time zone is a generalized time zone, e.g., @code{EGT}, Calc
17486examines the date being converted to tell whether to use standard 17486examines the date being converted to tell whether to use standard
17487or daylight savings time. But if the current time zone is explicit, 17487or daylight saving time. But if the current time zone is explicit,
17488e.g., @code{EST} or @code{EDT}, then that adjustment is used exactly 17488e.g., @code{EST} or @code{EDT}, then that adjustment is used exactly
17489and Calc's daylight savings algorithm is not consulted. 17489and Calc's daylight saving algorithm is not consulted.
17490 17490
17491Some places don't follow the usual rules for daylight savings time. 17491Some places don't follow the usual rules for daylight saving time.
17492The state of Arizona, for example, does not observe daylight savings 17492The state of Arizona, for example, does not observe daylight saving
17493time. If you run Calc during the winter season in Arizona, the 17493time. If you run Calc during the winter season in Arizona, the
17494Unix @code{date} command will report @code{MST} time zone, which 17494Unix @code{date} command will report @code{MST} time zone, which
17495Calc will change to @code{MGT}. If you then convert a time that 17495Calc will change to @code{MGT}. If you then convert a time that
17496lies in the summer months, Calc will apply an incorrect daylight 17496lies in the summer months, Calc will apply an incorrect daylight
17497savings time adjustment. To avoid this, set your @code{TimeZone} 17497saving time adjustment. To avoid this, set your @code{TimeZone}
17498variable explicitly to @code{MST} to force the use of standard, 17498variable explicitly to @code{MST} to force the use of standard,
17499non-daylight-savings time. 17499non-daylight-saving time.
17500 17500
17501@vindex math-daylight-savings-hook 17501@vindex math-daylight-savings-hook
17502@findex math-std-daylight-savings 17502@findex math-std-daylight-savings
17503By default Calc always considers daylight savings time to begin at 17503By default Calc always considers daylight saving time to begin at
175042 a.m.@: on the first Sunday of April, and to end at 2 a.m.@: on the 175042 a.m.@: on the second Sunday of March, and to end at 2 a.m.@: on the
17505last Sunday of October. This is the rule that has been in effect 17505first Sunday of November. This is the rule that has been in effect
17506in North America since 1987. If you are in a country that uses 17506in North America since 2007. If you are in a country that uses
17507different rules for computing daylight savings time, you have two 17507different rules for computing daylight saving time, you have two
17508choices: Write your own daylight savings hook, or control time 17508choices: Write your own daylight saving hook, or control time
17509zones explicitly by setting the @code{TimeZone} variable and/or 17509zones explicitly by setting the @code{TimeZone} variable and/or
17510always giving a time-zone argument for the conversion functions. 17510always giving a time-zone argument for the conversion functions.
17511 17511
17512The Lisp variable @code{math-daylight-savings-hook} holds the 17512The Lisp variable @code{math-daylight-savings-hook} holds the
17513name of a function that is used to compute the daylight savings 17513name of a function that is used to compute the daylight saving
17514adjustment for a given date. The default is 17514adjustment for a given date. The default is
17515@code{math-std-daylight-savings}, which computes an adjustment 17515@code{math-std-daylight-savings}, which computes an adjustment
17516(either 0 or @mathit{-1}) using the North American rules given above. 17516(either 0 or @mathit{-1}) using the North American rules given above.
17517 17517
17518The daylight savings hook function is called with four arguments: 17518The daylight saving hook function is called with four arguments:
17519The date, as a floating-point number in standard Calc format; 17519The date, as a floating-point number in standard Calc format;
17520a six-element list of the date decomposed into year, month, day, 17520a six-element list of the date decomposed into year, month, day,
17521hour, minute, and second, respectively; a string which contains 17521hour, minute, and second, respectively; a string which contains
@@ -17525,18 +17525,18 @@ converting into a generalized time zone (see below).
17525 17525
17526@findex math-prev-weekday-in-month 17526@findex math-prev-weekday-in-month
17527The Lisp function @code{math-prev-weekday-in-month} is useful for 17527The Lisp function @code{math-prev-weekday-in-month} is useful for
17528daylight savings computations. This is an internal version of 17528daylight saving computations. This is an internal version of
17529the user-level @code{pwday} function described in the previous 17529the user-level @code{pwday} function described in the previous
17530section. It takes four arguments: The floating-point date value, 17530section. It takes four arguments: The floating-point date value,
17531the corresponding six-element date list, the day-of-month number, 17531the corresponding six-element date list, the day-of-month number,
17532and the weekday number (0-6). 17532and the weekday number (0-6).
17533 17533
17534The default daylight savings hook ignores the time zone name, but a 17534The default daylight saving hook ignores the time zone name, but a
17535more sophisticated hook could use different algorithms for different 17535more sophisticated hook could use different algorithms for different
17536time zones. It would also be possible to use different algorithms 17536time zones. It would also be possible to use different algorithms
17537depending on the year number, but the default hook always uses the 17537depending on the year number, but the default hook always uses the
17538algorithm for 1987 and later. Here is a listing of the default 17538algorithm for 1987 and later. Here is a listing of the default
17539daylight savings hook: 17539daylight saving hook:
17540 17540
17541@smallexample 17541@smallexample
17542(defun math-std-daylight-savings (date dt zone bump) 17542(defun math-std-daylight-savings (date dt zone bump)
@@ -17566,25 +17566,25 @@ adjustments shown above ensure that the conversion behaves correctly
17566and reasonably around the 2 a.m.@: transition in each direction. 17566and reasonably around the 2 a.m.@: transition in each direction.
17567 17567
17568There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the 17568There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the
17569beginning of daylight savings time; converting a date/time form that 17569beginning of daylight saving time; converting a date/time form that
17570falls in this hour results in a time value for the following hour, 17570falls in this hour results in a time value for the following hour,
17571from 3 a.m.@: to 4 a.m. At the end of daylight savings time, the 17571from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the
17572hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time 17572hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time
17573form that falls in this hour results in a time value for the first 17573form that falls in this hour results in a time value for the first
17574manifestation of that time (@emph{not} the one that occurs one hour later). 17574manifestation of that time (@emph{not} the one that occurs one hour later).
17575 17575
17576If @code{math-daylight-savings-hook} is @code{nil}, then the 17576If @code{math-daylight-savings-hook} is @code{nil}, then the
17577daylight savings adjustment is always taken to be zero. 17577daylight saving adjustment is always taken to be zero.
17578 17578
17579In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} 17579In algebraic formulas, @samp{tzone(@var{zone}, @var{date})}
17580computes the time zone adjustment for a given zone name at a 17580computes the time zone adjustment for a given zone name at a
17581given date. The @var{date} is ignored unless @var{zone} is a 17581given date. The @var{date} is ignored unless @var{zone} is a
17582generalized time zone. If @var{date} is a date form, the 17582generalized time zone. If @var{date} is a date form, the
17583daylight savings computation is applied to it as it appears. 17583daylight saving computation is applied to it as it appears.
17584If @var{date} is a numeric date value, it is adjusted for the 17584If @var{date} is a numeric date value, it is adjusted for the
17585daylight-savings version of @var{zone} before being given to 17585daylight-saving version of @var{zone} before being given to
17586the daylight savings hook. This odd-sounding rule ensures 17586the daylight saving hook. This odd-sounding rule ensures
17587that the daylight-savings computation is always done in 17587that the daylight-saving computation is always done in
17588local time, not in the GMT time that a numeric @var{date} 17588local time, not in the GMT time that a numeric @var{date}
17589is typically represented in. 17589is typically represented in.
17590 17590
@@ -17593,9 +17593,9 @@ is typically represented in.
17593@end ignore 17593@end ignore
17594@tindex dsadj 17594@tindex dsadj
17595The @samp{dsadj(@var{date}, @var{zone})} function computes the 17595The @samp{dsadj(@var{date}, @var{zone})} function computes the
17596daylight savings adjustment that is appropriate for @var{date} in 17596daylight saving adjustment that is appropriate for @var{date} in
17597time zone @var{zone}. If @var{zone} is explicitly in or not in 17597time zone @var{zone}. If @var{zone} is explicitly in or not in
17598daylight savings time (e.g., @code{PDT} or @code{PST}) the 17598daylight saving time (e.g., @code{PDT} or @code{PST}) the
17599@var{date} is ignored. If @var{zone} is a generalized time zone, 17599@var{date} is ignored. If @var{zone} is a generalized time zone,
17600the algorithms described above are used. If @var{zone} is omitted, 17600the algorithms described above are used. If @var{zone} is omitted,
17601the computation is done for the current time zone. 17601the computation is done for the current time zone.