[Python-checkins] python/dist/src/Doc/lib libtime.tex,1.48.6.3,1.48.6.4
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Tue, 04 Feb 2003 07:13:27 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv27806
Modified Files:
Tag: release22-maint
libtime.tex
Log Message:
Update to better reflect the usage of struct_time instances throughout;
continuing to call these "time tuples" is misleading at best.
Closes SF bug #671731; backported from rev 1.55.
Index: libtime.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libtime.tex,v
retrieving revision 1.48.6.3
retrieving revision 1.48.6.4
diff -C2 -d -r1.48.6.3 -r1.48.6.4
*** libtime.tex 15 Nov 2002 23:01:37 -0000 1.48.6.3
--- libtime.tex 4 Feb 2003 15:13:25 -0000 1.48.6.4
***************
*** 30,39 ****
depends on the platform's C library, which generally doesn't have year
2000 issues, since all dates and times are represented internally as
! seconds since the epoch. Functions accepting a time tuple (see below)
! generally require a 4-digit year. For backward compatibility, 2-digit
! years are supported if the module variable \code{accept2dyear} is a
! non-zero integer; this variable is initialized to \code{1} unless the
! environment variable \envvar{PYTHONY2K} is set to a non-empty string,
! in which case it is initialized to \code{0}. Thus, you can set
\envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
years for all year input. When 2-digit years are accepted, they are
--- 30,40 ----
depends on the platform's C library, which generally doesn't have year
2000 issues, since all dates and times are represented internally as
! seconds since the epoch. Functions accepting a \class{struct_time}
! (see below) generally require a 4-digit year. For backward
! compatibility, 2-digit years are supported if the module variable
! \code{accept2dyear} is a non-zero integer; this variable is
! initialized to \code{1} unless the environment variable
! \envvar{PYTHONY2K} is set to a non-empty string, in which case it is
! initialized to \code{0}. Thus, you can set
\envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
years for all year input. When 2-digit years are accepted, they are
***************
*** 100,108 ****
When a tuple with an incorrect length is passed to a function
! expecting a time tuple, or having elements of the wrong type, a
\exception{TypeError} is raised.
\versionchanged[The time value sequence was changed from a tuple to a
! specialized type, with the addition of attribute names
for the fields]{2.2}
\end{itemize}
--- 101,109 ----
When a tuple with an incorrect length is passed to a function
! expecting a \class{struct_time}, or having elements of the wrong type, a
\exception{TypeError} is raised.
\versionchanged[The time value sequence was changed from a tuple to a
! \class{struct_time}, with the addition of attribute names
for the fields]{2.2}
\end{itemize}
***************
*** 125,137 ****
\end{datadesc}
! \begin{funcdesc}{asctime}{\optional{tuple}}
! Convert a tuple representing a time as returned by \function{gmtime()}
or \function{localtime()} to a 24-character string of the following form:
! \code{'Sun Jun 20 23:21:05 1993'}. If \var{tuple} is not provided, the
current time as returned by \function{localtime()} is used.
Locale information is not used by \function{asctime()}.
\note{Unlike the C function of the same name, there is no trailing
newline.}
! \versionchanged[Allowed \var{tuple} to be omitted]{2.1}
\end{funcdesc}
--- 126,139 ----
\end{datadesc}
! \begin{funcdesc}{asctime}{\optional{t}}
! Convert a tuple or \class{struct_time} representing a time as returned
! by \function{gmtime()}
or \function{localtime()} to a 24-character string of the following form:
! \code{'Sun Jun 20 23:21:05 1993'}. If \var{t} is not provided, the
current time as returned by \function{localtime()} is used.
Locale information is not used by \function{asctime()}.
\note{Unlike the C function of the same name, there is no trailing
newline.}
! \versionchanged[Allowed \var{t} to be omitted]{2.1}
\end{funcdesc}
***************
*** 165,173 ****
\begin{funcdesc}{gmtime}{\optional{secs}}
! Convert a time expressed in seconds since the epoch to a time tuple
in UTC in which the dst flag is always zero. If \var{secs} is not
provided, the current time as returned by \function{time()} is used.
Fractions of a second are ignored. See above for a description of the
! tuple lay-out.
\versionchanged[Allowed \var{secs} to be omitted]{2.1}
\end{funcdesc}
--- 167,175 ----
\begin{funcdesc}{gmtime}{\optional{secs}}
! Convert a time expressed in seconds since the epoch to a \class{struct_time}
in UTC in which the dst flag is always zero. If \var{secs} is not
provided, the current time as returned by \function{time()} is used.
Fractions of a second are ignored. See above for a description of the
! \class{struct_time} object.
\versionchanged[Allowed \var{secs} to be omitted]{2.1}
\end{funcdesc}
***************
*** 179,186 ****
\end{funcdesc}
! \begin{funcdesc}{mktime}{tuple}
This is the inverse function of \function{localtime()}. Its argument
! is the full 9-tuple (since the dst flag is needed; use \code{-1} as
! the dst flag if it is unknown) which expresses the time in
\emph{local} time, not UTC. It returns a floating point number, for
compatibility with \function{time()}. If the input value cannot be
--- 181,189 ----
\end{funcdesc}
! \begin{funcdesc}{mktime}{t}
This is the inverse function of \function{localtime()}. Its argument
! is the \class{struct_time} or full 9-tuple (since the dst flag is
! needed; use \code{-1} as the dst flag if it is unknown) which
! expresses the time in
\emph{local} time, not UTC. It returns a floating point number, for
compatibility with \function{time()}. If the input value cannot be
***************
*** 201,210 ****
\end{funcdesc}
! \begin{funcdesc}{strftime}{format\optional{, tuple}}
! Convert a tuple representing a time as returned by \function{gmtime()}
! or \function{localtime()} to a string as specified by the \var{format}
! argument. If \var{tuple} is not provided, the current time as returned by
! \function{localtime()} is used. \var{format} must be a string.
! \versionchanged[Allowed \var{tuple} to be omitted]{2.1}
The following directives can be embedded in the \var{format} string.
--- 204,214 ----
\end{funcdesc}
! \begin{funcdesc}{strftime}{format\optional{, t}}
! Convert a tuple or \class{struct_time} representing a time as returned
! by \function{gmtime()} or \function{localtime()} to a string as
! specified by the \var{format} argument. If \var{t} is not
! provided, the current time as returned by \function{localtime()} is
! used. \var{format} must be a string.
! \versionchanged[Allowed \var{t} to be omitted]{2.1}
The following directives can be embedded in the \var{format} string.
***************
*** 278,282 ****
\begin{funcdesc}{strptime}{string\optional{, format}}
Parse a string representing a time according to a format. The return
! value is a tuple as returned by \function{gmtime()} or
\function{localtime()}. The \var{format} parameter uses the same
directives as those used by \function{strftime()}; it defaults to
--- 282,286 ----
\begin{funcdesc}{strptime}{string\optional{, format}}
Parse a string representing a time according to a format. The return
! value is a \class{struct_time} as returned by \function{gmtime()} or
\function{localtime()}. The \var{format} parameter uses the same
directives as those used by \function{strftime()}; it defaults to