summaryrefslogtreecommitdiff
path: root/Doc/lib/libtime.tex
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1994-01-02 01:22:07 +0000
committerGuido van Rossum <guido@python.org>1994-01-02 01:22:07 +0000
commit5358a5d5edc5fa2c86e92ee752bbdd8ca2c19f2e (patch)
tree633660732fe1d4757bf1d7e36c94e8ff97c9afb1 /Doc/lib/libtime.tex
parent5b38bb657f01bd87636f87ad5ddfc92930cd8148 (diff)
downloadcpython-5358a5d5edc5fa2c86e92ee752bbdd8ca2c19f2e.tar.gz
Restructured library documentation
Diffstat (limited to 'Doc/lib/libtime.tex')
-rw-r--r--Doc/lib/libtime.tex121
1 files changed, 121 insertions, 0 deletions
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
new file mode 100644
index 0000000000..fe8b7dcba2
--- /dev/null
+++ b/Doc/lib/libtime.tex
@@ -0,0 +1,121 @@
+\section{Built-in Module \sectcode{time}}
+
+\bimodindex{time}
+This module provides various time-related functions.
+It is always available. (On some systems, not all functions may
+exist; e.g. the ``milli'' variants can't always be implemented.)
+
+An explanation of some terminology and conventions is in order.
+
+\begin{itemize}
+
+\item
+The ``epoch'' is the point where the time starts. On January 1st 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 the first
+element of \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.
+
+\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.
+
+\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 every 1/50th or
+1/100th of a second, and on the Mac, it ticks 60 times a second.
+
+\end{itemize}
+
+Functions and data items are:
+
+\renewcommand{\indexsubitem}{(in module time)}
+
+\begin{datadesc}{altzone}
+The offset of the local DST timezone, in seconds west of the 0th
+meridian, if one is defined. 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}{ctime}{secs}
+Convert a time expressed in seconds since the epoch to a string
+representing local time. \code{ctime(t)} is equivalent to
+\code{asctime(localtime(t))}.
+\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 tuple of 9
+integers, in UTC: 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), dst flag (always zero). Fractions of a second are
+ignored. Note subtle differences with the C function of this name.
+\end{funcdesc}
+
+\begin{funcdesc}{localtime}{secs}
+Like \code{gmtime} but converts to local time. The dst flag is set
+to 1 when DST applies to the given time.
+\end{funcdesc}
+
+\begin{funcdesc}{millisleep}{msecs}
+Suspend execution for the given number of milliseconds. (Obsolete,
+you can now use use \code{sleep} with a floating point argument.)
+\end{funcdesc}
+
+\begin{funcdesc}{millitimer}{}
+Return the number of milliseconds of real time elapsed since some
+point in the past that is fixed per execution of the python
+interpreter (but may change in each following run). The return value
+may be negative, and it may wrap around.
+\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). It returns an integer.
+\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}{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. An alternative for measuring precise
+intervals is \code{millitimer}.
+\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}