Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtime.tex @ 3720:b341def4eef8 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Ignore latex intermediate products.
author Guido van Rossum <guido@python.org>
date Wed, 26 Jun 1996 19:30:01 +0000
parents c120a483d590
children 0853166f0d69
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{time}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{time}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module provides various time-related functions.
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
5 It is always available.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 An explanation of some terminology and conventions is in order.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 \item
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
12 The ``epoch'' is the point where the time starts. On January 1st of that
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 year, at 0 hours, the ``time since the epoch'' is zero. For UNIX, the
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
14 epoch is 1970. To find out what the epoch is, look at \code{gmtime(0)}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 UTC is Coordinated Universal Time (formerly known as Greenwich Mean
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 Time). The acronym UTC is not a mistake but a compromise between
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 English and French.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 DST is Daylight Saving Time, an adjustment of the timezone by
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 (usually) one hour during part of the year. DST rules are magic
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 (determined by local law) and can change from year to year. The C
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 library has a table containing the local rules (often it is read from
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 a system file for flexibility) and is the only source of True Wisdom
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 in this respect.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 The precision of the various real-time functions may be less than
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 suggested by the units in which their value or argument is expressed.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
32 E.g.\ on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
33 second, and on the Mac, times are only accurate to whole seconds.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \end{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
37 The module defines the following functions and data items:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 \renewcommand{\indexsubitem}{(in module time)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \begin{datadesc}{altzone}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 The offset of the local DST timezone, in seconds west of the 0th
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
43 meridian, if one is defined. Negative if the local DST timezone is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
44 east of the 0th meridian (as in Western Europe, including the UK).
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
45 Only use this if \code{daylight} is nonzero.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \begin{funcdesc}{asctime}{tuple}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 Convert a tuple representing a time as returned by \code{gmtime()} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \code{localtime()} to a 24-character string of the following form:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 the same name, there is no trailing newline.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
57 \begin{funcdesc}{clock}{}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
58 Return the current CPU time as a floating point number expressed in
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
59 seconds. The precision, and in fact the very definiton of the meaning
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
60 of ``CPU time'', depends on that of the C function of the same name.
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
61 \end{funcdesc}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
62
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
63
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \begin{funcdesc}{ctime}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 Convert a time expressed in seconds since the epoch to a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 representing local time. \code{ctime(t)} is equivalent to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 \code{asctime(localtime(t))}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \begin{datadesc}{daylight}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 Nonzero if a DST timezone is defined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \begin{funcdesc}{gmtime}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 Convert a time expressed in seconds since the epoch to a tuple of 9
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1807
diff changeset
76 integers, in UTC: year (e.g.\ 1993), month (1--12), day (1--31), hour
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1807
diff changeset
77 (0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1807
diff changeset
78 Julian day (1--366), dst flag (always zero). Fractions of a second are
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 ignored. Note subtle differences with the C function of this name.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \begin{funcdesc}{localtime}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 Like \code{gmtime} but converts to local time. The dst flag is set
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 to 1 when DST applies to the given time.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \begin{funcdesc}{mktime}{tuple}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 This is the inverse function of \code{localtime}. Its argument is the
3714
c120a483d590 mktime returns a float now.
Guido van Rossum <guido@python.org>
parents: 3380
diff changeset
89 full 9-tuple (since the dst flag is needed). It returns a floating
c120a483d590 mktime returns a float now.
Guido van Rossum <guido@python.org>
parents: 3380
diff changeset
90 point number, for compatibility with \code{time.time()}. If the input
c120a483d590 mktime returns a float now.
Guido van Rossum <guido@python.org>
parents: 3380
diff changeset
91 value can't be represented as a valid time, OverflowError is raised.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \begin{funcdesc}{sleep}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 Suspend execution for the given number of seconds. The argument may
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 be a floating point number to indicate a more precise sleep time.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
3085
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
99 \begin{funcdesc}{strftime}{format, tuple}
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
100 Convert a tuple representing a time as returned by \code{gmtime()} or
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
101 \code{localtime()} to a string as specified by the format argument.
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
102 See the \code{strftime(3)} man page for details of the syntax of
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
103 format strings.
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
104 \end{funcdesc}
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
105
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 \begin{funcdesc}{time}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 Return the time as a floating point number expressed in seconds since
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 the epoch, in UTC. Note that even though the time is always returned
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 as a floating point number, not all systems provide time with a better
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
110 precision than 1 second.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 \begin{datadesc}{timezone}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 The offset of the local (non-DST) timezone, in seconds west of the 0th
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 meridian (i.e. negative in most of Western Europe, positive in the US,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 zero in the UK).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 \begin{datadesc}{tzname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 A tuple of two strings: the first is the name of the local non-DST
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 timezone, the second is the name of the local DST timezone. If no DST
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 timezone is defined, the second string should not be used.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \end{datadesc}