diff options
Diffstat (limited to 'Doc/libtime.tex')
| -rw-r--r-- | Doc/libtime.tex | 189 |
1 files changed, 0 insertions, 189 deletions
diff --git a/Doc/libtime.tex b/Doc/libtime.tex deleted file mode 100644 index ed4f4ef..0000000 --- a/Doc/libtime.tex +++ /dev/null @@ -1,189 +0,0 @@ -\section{Built-in Module \module{time}} -\label{module-time} -\bimodindex{time} - -This module provides various time-related functions. -It is always available. - -An explanation of some terminology and conventions is in order. - -\begin{itemize} - -\item -The \dfn{epoch}\index{epoch} is the point where the time starts. On -January 1st of that year, at 0 hours, the ``time since the epoch'' is -zero. For \UNIX{}, the epoch is 1970. To find out what the epoch is, -look at \code{gmtime(0)}. - -\item -UTC is Coordinated Universal Time (formerly known as Greenwich Mean -Time). The acronym UTC is not a mistake but a compromise between -English and French.% -\index{UTC}% -\index{Coordinated Universal Time}% -\index{Greenwich Mean Time} - -\item -DST is Daylight Saving Time, an adjustment of the timezone by -(usually) one hour during part of the year. DST rules are magic -(determined by local law) and can change from year to year. The \C{} -library has a table containing the local rules (often it is read from -a system file for flexibility) and is the only source of True Wisdom -in this respect.% -\index{Daylight Saving Time} - -\item -The precision of the various real-time functions may be less than -suggested by the units in which their value or argument is expressed. -E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a -second, and on the Mac, times are only accurate to whole seconds. - -\item -On the other hand, the precision of \function{time()} and -\function{sleep()} is better than their \UNIX{} equivalents: times are -expressed as floating point numbers, \function{time()} returns the -most accurate time available (using \UNIX{} \cfunction{gettimeofday()} -where available), and \function{sleep()} will accept a time with a -nonzero fraction (\UNIX{} \cfunction{select()} is used to implement -this, where available). - -\item -The time tuple as returned by \function{gmtime()} and -\function{localtime()}, or as accpted by \function{mktime()} is a -tuple of 9 integers: year (e.g.\ 1993), month (1--12), day (1--31), -hour (0--23), minute (0--59), second (0--59), weekday (0--6, monday is -0), Julian day (1--366) and daylight savings flag (-1, 0 or 1). -Note that unlike the \C{} structure, the month value is a range of 1-12, not -0-11. A year value less than 100 will typically be silently converted to -1900 plus the year value. A \code{-1} argument as daylight savings -flag, passed to \function{mktime()} will usually result in the correct -daylight savings state to be filled in. - -\end{itemize} - -The module defines the following functions and data items: - - -\begin{datadesc}{altzone} -The offset of the local DST timezone, in seconds west of the 0th -meridian, if one is defined. Negative if the local DST timezone is -east of the 0th meridian (as in Western Europe, including the UK). -Only use this if \code{daylight} is nonzero. -\end{datadesc} - -\begin{funcdesc}{asctime}{tuple} -Convert a tuple representing a time as returned by \code{gmtime()} or -\code{localtime()} to a 24-character string of the following form: -\code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of -the same name, there is no trailing newline. -\end{funcdesc} - -\begin{funcdesc}{clock}{} -Return the current CPU time as a floating point number expressed in -seconds. The precision, and in fact the very definiton of the meaning -of ``CPU time''\index{CPU time}, depends on that of the \C{} function -of the same name, but in any case, this is the function to use for -benchmarking\index{benchmarking} Python or timing algorithms. -\end{funcdesc} - -\begin{funcdesc}{ctime}{secs} -Convert a time expressed in seconds since the epoch to a string -representing local time. \code{ctime(\var{secs})} is equivalent to -\code{asctime(localtime(\var{secs}))}. -\end{funcdesc} - -\begin{datadesc}{daylight} -Nonzero if a DST timezone is defined. -\end{datadesc} - -\begin{funcdesc}{gmtime}{secs} -Convert a time expressed in seconds since the epoch to a time tuple -in UTC in which the dst flag is always zero. Fractions of a second are -ignored. -\end{funcdesc} - -\begin{funcdesc}{localtime}{secs} -Like \function{gmtime()} but converts to local time. The dst flag is -set to \code{1} when DST applies to the given time. -\end{funcdesc} - -\begin{funcdesc}{mktime}{tuple} -This is the inverse function of \code{localtime}. Its argument is the -full 9-tuple (since the dst flag is needed --- pass \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 represented as a valid time, \exception{OverflowError} -is raised. -\end{funcdesc} - -\begin{funcdesc}{sleep}{secs} -Suspend execution for the given number of seconds. The argument may -be a floating point number to indicate a more precise sleep time. -\end{funcdesc} - -\begin{funcdesc}{strftime}{format, tuple} -Convert a tuple representing a time as returned by \code{gmtime()} or -\code{localtime()} to a string as specified by the format argument. - -The following directives, shown without the optional field width and -precision specification, are replaced by the indicated characters: - -\begin{tableii}{c|p{24em}}{code}{Directive}{Meaning} - \lineii{\%a}{Locale's abbreviated weekday name.} - \lineii{\%A}{Locale's full weekday name.} - \lineii{\%b}{Locale's abbreviated month name.} - \lineii{\%B}{Locale's full month name.} - \lineii{\%c}{Locale's appropriate date and time representation.} - \lineii{\%d}{Day of the month as a decimal number [01,31].} - \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].} - \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].} - \lineii{\%j}{Day of the year as a decimal number [001,366].} - \lineii{\%m}{Month as a decimal number [01,12].} - \lineii{\%M}{Minute as a decimal number [00,59].} - \lineii{\%p}{Locale's equivalent of either AM or PM.} - \lineii{\%S}{Second as a decimal number [00,61].} - \lineii{\%U}{Week number of the year (Sunday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].} - \lineii{\%W}{Week number of the year (Monday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%x}{Locale's appropriate date representation.} - \lineii{\%X}{Locale's appropriate time representation.} - \lineii{\%y}{Year without century as a decimal number [00,99].} - \lineii{\%Y}{Year with century as a decimal number.} - \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).} - \lineii{\%\%}{\%} -\end{tableii} - -Additional directives may be supported on certain platforms, but -only the ones listed here have a meaning standardized by ANSI C. - -On some platforms, an optional field width and precision -specification can immediately follow the initial \code{\%} of a -directive in the following order; this is also not portable. -The field width is normally 2 except for \code{\%j} where it is 3. - -\end{funcdesc} - -\begin{funcdesc}{time}{} -Return the time as a floating point number expressed in seconds since -the epoch, in UTC. Note that even though the time is always returned -as a floating point number, not all systems provide time with a better -precision than 1 second. -\end{funcdesc} - -\begin{datadesc}{timezone} -The offset of the local (non-DST) timezone, in seconds west of the 0th -meridian (i.e. negative in most of Western Europe, positive in the US, -zero in the UK). -\end{datadesc} - -\begin{datadesc}{tzname} -A tuple of two strings: the first is the name of the local non-DST -timezone, the second is the name of the local DST timezone. If no DST -timezone is defined, the second string should not be used. -\end{datadesc} - |