summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libdatetime.tex
diff options
context:
space:
mode:
authorAndrew M. Kuchling <amk@amk.ca>2003-02-05 21:15:38 (GMT)
committerAndrew M. Kuchling <amk@amk.ca>2003-02-05 21:15:38 (GMT)
commit570e35870a131dc65dde2835972abb6fdf60a117 (patch)
tree155b05c7d999335d7409fdba690bd419a02e287f /Doc/lib/libdatetime.tex
parent62235e701e377fd1e4934bc029b9b86d8dc3ed95 (diff)
downloadcpython-570e35870a131dc65dde2835972abb6fdf60a117.zip
cpython-570e35870a131dc65dde2835972abb6fdf60a117.tar.gz
cpython-570e35870a131dc65dde2835972abb6fdf60a117.tar.bz2
Markup fixes; in particular, the tables are now reasonable width
Diffstat (limited to 'Doc/lib/libdatetime.tex')
-rw-r--r--Doc/lib/libdatetime.tex221
1 files changed, 117 insertions, 104 deletions
diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
index fa86e9f..f49fc49 100644
--- a/Doc/lib/libdatetime.tex
+++ b/Doc/lib/libdatetime.tex
@@ -34,9 +34,9 @@ the abstract \class{tzinfo} class. These \class{tzinfo} objects
capture information about the offset from UTC time, the time zone
name, and whether Daylight Saving Time is in effect. Note that no
concrete \class{tzinfo} classes are supplied by the \module{datetime}
-module. Instead, they provide a framework for incorporating the level
-of detail an application may require. The rules for time adjustment across
-the world are more political than rational, and there is no standard
+module. Supporting timezones at whatever level of detail is required
+is up to the application. The rules for time adjustment across the
+world are more political than rational, and there is no standard
suitable for every application.
The \module{datetime} module exports the following constants:
@@ -201,38 +201,38 @@ Instance attributes (read-only):
Supported operations:
% XXX this table is too wide!
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{t1} = \var{t2} + \var{t3}}
+\begin{tableii}{c|l}{code}{Operation}{Result}
+ \lineii{\var{t1} = \var{t2} + \var{t3}}
{Sum of \var{t2} and \var{t3}.
Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
- == \var{t2} are true.}
- {(1)}
- \lineiii{\var{t1} = \var{t2} - \var{t3}}
- {Difference of \var{t2} and \var{t3}. Afterwards \var{t1} ==
- \var{t2} - \var{t3} and \var{t2} == \var{t1} + \var{t3} are
- true.}
- {(1)}
- \lineiii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
+ == \var{t2} are true.
+ (1)}
+ \lineii{\var{t1} = \var{t2} - \var{t3}}
+ {Difference of \var{t2} and \var{t3}.
+ Afterwards \var{t1} == \var{t2} - \var{t3} and \var{t2} == \var{t1} + \var{t3} are
+ true.
+ (1)}
+ \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
{Delta multiplied by an integer or long.
Afterwards \var{t1} // i == \var{t2} is true,
- provided \code{i != 0}.
- In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.}
- {(1)}
- \lineiii{\var{t1} = \var{t2} // \var{i}}
- {The floor is computed and the remainder (if any) is thrown away.}
- {(3)}
- \lineiii{+\var{t1}}
- {Returns a \class{timedelta} object with the same value.}
- {(2)}
- \lineiii{-\var{t1}}
+ provided \code{i != 0}.}
+ \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.
+ (1)}
+ \lineii{\var{t1} = \var{t2} // \var{i}}
+ {The floor is computed and the remainder (if any) is thrown away.
+ (3)}
+ \lineii{+\var{t1}}
+ {Returns a \class{timedelta} object with the same value.
+ (2)}
+ \lineii{-\var{t1}}
{equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
- -\var{t1.microseconds}), and to \var{t1}* -1.}
- {(1)(4)}
- \lineiii{abs(\var{t})}
+ -\var{t1.microseconds}), and to \var{t1}* -1.
+ (1)(4)}
+ \lineii{abs(\var{t})}
{equivalent to +\var{t} when \code{t.days >= 0}, and to
- -\var{t} when \code{t.days < 0}.}
- {(2)}
-\end{tableiii}
+ -\var{t} when \code{t.days < 0}.
+ (2)}
+\end{tableii}
\noindent
Notes:
@@ -348,56 +348,66 @@ Instance attributes (read-only):
Supported operations:
% XXX rewrite to be a table
-\begin{itemize}
- \item
- date1 + timedelta -> date2
+\begin{tableii}{c|l}{code}{Operation}{Result}
+ \lineii{\var{date2} = \var{date1} + \var{timedelta}}
+ {\var{date2} is \code{\var{timedelta}.days} days removed from
+ \var{date1}. (1)}
- timedelta + date1 -> date2
- date2 is timedelta.days days removed from the date1, moving forward
- in time if timedelta.days > 0, or backward if timedetla.days < 0.
- date2 - date1 == timedelta.days after. timedelta.seconds and
- timedelta.microseconds are ignored. \exception{OverflowError} is
- raised if date2.year would be smaller than \constant{MINYEAR} or
- larger than \constant{MAXYEAR}.
+ \lineii{\var{date2} = \var{date1} - \var{timedelta}}
+ {Computes \var{date2} such that \code{\var{date2} + \var{timedelta}
+ == \var{date1}}. (2)}
- \item
- date1 - timedelta -> date2
+ \lineii{\var{timedelta} = \var{date1} - \var{date2}}
+ {(3)}
- Computes the date2 such that date2 + timedelta == date1. This
- isn't quite equivalent to date1 + (-timedelta), because -timedelta
- in isolation can overflow in cases where date1 - timedelta does
- not. timedelta.seconds and timedelta.microseconds are ignored.
+ \lineii{\var{date1}<\var{date2}}
+ {\var{date1} is considered less than \var{date2} when \var{date1}
+ precedes \var{date2} in time. (4)}
- \item
- date1 - date2 -> timedelta
+\end{tableii}
+
+Notes:
+\begin{description}
+
+\item[(1)]
+ \var{date2} is moved forward in time if \code{\var{timedelta}.days
+ > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward
+ \code{\var{date2} - \var{date1} == \var{timedelta}.days}.
+ \code{\var{timedelta}.seconds} and
+ \code{\var{timedelta}.microseconds} are ignored.
+ \exception{OverflowError} is raised if \code{\var{date2}.year}
+ would be smaller than \constant{MINYEAR} or larger than
+ \constant{MAXYEAR}.
- This is exact, and cannot overflow. timedelta.seconds and
+\item[(2)]
+ This isn't quite equivalent to date1 +
+ (-timedelta), because -timedelta in isolation can overflow in cases
+ where date1 - timedelta does not. \code{\var{timedelta}.seconds}
+ and \code{\var{timedelta}.microseconds} are ignored.
+
+\item[(3)]
+This is exact, and cannot overflow. timedelta.seconds and
timedelta.microseconds are 0, and date2 + timedelta == date1
after.
- \item
- comparison of date to date, where date1 is considered less than
- date2 when date1 precedes date2 in time. In other words,
- date1 < date2 if and only if date1.toordinal() < date2.toordinal().
- \note{In order to stop comparison from falling back to the default
- scheme of comparing object addresses, date comparison
- normally raises \exception{TypeError} if the other comparand
- isn't also a \class{date} object. However, \code{NotImplemented}
- is returned instead if the other comparand has a
- \method{timetuple} attribute. This hook gives other kinds of
- date objects a chance at implementing mixed-type comparison.}
-
+\item[(4)]
+In other words, \code{date1 < date2}
+ if and only if \code{\var{date1}.toordinal() <
+ \var{date2}.toordinal()}.
+In order to stop comparison from falling back to the default
+scheme of comparing object addresses, date comparison
+normally raises \exception{TypeError} if the other comparand
+isn't also a \class{date} object. However, \code{NotImplemented}
+is returned instead if the other comparand has a
+\method{timetuple} attribute. This hook gives other kinds of
+date objects a chance at implementing mixed-type comparison.
- \item
- hash, use as dict key
+\end{description}
- \item
- efficient pickling
- \item
- in Boolean contexts, all \class{date} objects are considered to be true
-\end{itemize}
+Dates can be used as dictionary keys. In Boolean contexts, all
+\class{date} objects are considered to be true.
Instance methods:
@@ -414,10 +424,9 @@ Instance methods:
0, and the DST flag is -1.
\code{\var{d}.timetuple()} is equivalent to
\code{(\var{d}.year, \var{d}.month, \var{d}.day,
- 0, 0, 0, \# h, m, s
- \var{d}.weekday(), \# 0 is Monday
+ 0, 0, 0,
+ \var{d}.weekday(),
\var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
- \# day of year
-1)}
\end{methoddesc}
@@ -429,14 +438,14 @@ Instance methods:
\begin{methoddesc}{weekday}{}
Return the day of the week as an integer, where Monday is 0 and
- Sunday is 6. For example, date(2002, 12, 4).weekday() == 2, a
+ Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a
Wednesday.
See also \method{isoweekday()}.
\end{methoddesc}
\begin{methoddesc}{isoweekday}{}
Return the day of the week as an integer, where Monday is 1 and
- Sunday is 7. For example, date(2002, 12, 4).isoweekday() == 3, a
+ Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a
Wednesday.
See also \method{weekday()}, \method{isocalendar()}.
\end{methoddesc}
@@ -457,15 +466,15 @@ Instance methods:
For example, 2004 begins on a Thursday, so the first week of ISO
year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
2004, so that
-
- date(2003, 12, 29).isocalendar() == (2004, 1, 1)
- date(2004, 1, 4).isocalendar() == (2004, 1, 7)
+ \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
+ and
+ \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
\end{methoddesc}
\begin{methoddesc}{isoformat}{}
Return a string representing the date in ISO 8601 format,
'YYYY-MM-DD'. For example,
- date(2002, 12, 4).isoformat() == '2002-12-04'.
+ \code{date(2002, 12, 4).isoformat() == '2002-12-04'}.
\end{methoddesc}
\begin{methoddesc}{__str__}{}
@@ -590,8 +599,8 @@ Other constructors, all class methods:
\begin{methoddesc}{fromordinal}{ordinal}
Return the \class{datetime} corresponding to the proleptic
Gregorian ordinal, where January 1 of year 1 has ordinal 1.
- \exception{ValueError} is raised unless 1 <= ordinal <=
- datetime.max.toordinal(). The hour, minute, second and
+ \exception{ValueError} is raised unless \code{1 <= ordinal <=
+ datetime.max.toordinal()}. The hour, minute, second and
microsecond of the result are all 0,
and \member{tzinfo} is \code{None}.
\end{methoddesc}
@@ -661,24 +670,33 @@ Instance attributes (read-only):
Supported operations:
-\begin{itemize}
- \item
- datetime1 + timedelta -> datetime2
+\begin{tableii}{c|l}{code}{Operation}{Result}
+ \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}
+
+ \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
+
+ \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
+
+ \lineii{\var{datetime1} < \var{datetime2}}
+ {Compares \class{datetime} to \class{datetime}.
+ (4)}
+
+\end{tableii}
- timedelta + datetime1 -> datetime2
+\begin{description}
+
+\item[(1)]
datetime2 is a duration of timedelta removed from datetime1, moving
- forward in time if timedelta.days > 0, or backward if
- timedelta.days < 0. The result has the same \member{tzinfo} member
+ forward in time if \code{\var{timedelta}.days} > 0, or backward if
+ \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member
as the input datetime, and datetime2 - datetime1 == timedelta after.
\exception{OverflowError} is raised if datetime2.year would be
smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
Note that no time zone adjustments are done even if the input is an
aware object.
- \item
- datetime1 - timedelta -> datetime2
-
+\item[(2)]
Computes the datetime2 such that datetime2 + timedelta == datetime1.
As for addition, the result has the same \member{tzinfo} member
as the input datetime, and no time zone adjustments are done even
@@ -687,9 +705,7 @@ Supported operations:
-timedelta in isolation can overflow in cases where
datetime1 - timedelta does not.
- \item
- datetime1 - datetime2 -> timedelta
-
+\item[(3)]
Subtraction of a \class{datetime} from a
\class{datetime} is defined only if both
operands are naive, or if both are aware. If one is aware and the
@@ -708,11 +724,13 @@ Supported operations:
(\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
except that the implementation never overflows.
- \item
- comparison of \class{datetime} to \class{datetime},
- where \var{a} is considered less than \var{b}
- when \var{a} precedes \var{b} in time. If one comparand is naive and
- the other is aware, \exception{TypeError} is raised. If both
+\item[(4)]
+
+\var{datetime1} is considered less than \var{datetime2}
+when \var{datetime1} precedes \var{datetime2} in time.
+
+If one comparand is naive and
+the other is aware, \exception{TypeError} is raised. If both
comparands are aware, and have the same \member{tzinfo} member,
the common \member{tzinfo} member is ignored and the base datetimes
are compared. If both comparands are aware and have different
@@ -727,16 +745,11 @@ Supported operations:
kinds of date objects a chance at implementing mixed-type
comparison.}
- \item
- hash, use as dict key
+\end{description}
- \item
- efficient pickling
+\class{datetime} objects can be used as dictionary keys. In Boolean
+contexts, all \class{datetime} objects are considered to be true.
- \item
- in Boolean contexts, all \class{datetime} objects are considered
- to be true
-\end{itemize}
Instance methods:
@@ -773,7 +786,7 @@ Instance methods:
not be \code{None}, and \code{\var{self}.utcoffset()} must not return
\code{None}).
- If code{\var{self}.tzinfo} is \var{tz},
+ If \code{\var{self}.tzinfo} is \var{tz},
\code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no
adjustment of date or time members is performed.
Else the result is local time in time zone \var{tz}, representing the