Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 8cf2db4

Browse files
gvanrossumgvanrossum
committed
Moved description of mktime 9-tuple to top.
Added description of strftime format string. Minor small editing.
1 parent f4d0d57 commit 8cf2db4

2 files changed

Lines changed: 178 additions & 22 deletions

File tree

‎Doc/lib/libtime.tex‎

Lines changed: 89 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,19 @@ \section{Built-in Module \sectcode{time}}
3232
E.g.\ on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
3333
second, and on the Mac, times are only accurate to whole seconds.
3434

35+
\item
36+
The time tuple as returned by \code{gmtime()} and \code{localtime()},
37+
or as accpted by \code{mktime()} is a tuple of 9
38+
integers: year (e.g.\ 1993), month (1--12), day (1--31), hour
39+
(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
40+
Julian day (1--366) and daylight savings flag (-1, 0 or 1).
41+
Note that unlike the C structure, the month value is a range of 1-12, not
42+
0-11. A year value of $<$ 100 will typically be silently converted to
43+
1900 $+$ year value. A -1 argument as daylight savings flag, passed to
44+
\code{mktime()} will usually result in the correct daylight savings
45+
state to be filled in.
46+
47+
3548
\end{itemize}
3649

3750
The module defines the following functions and data items:
@@ -45,22 +58,19 @@ \section{Built-in Module \sectcode{time}}
4558
Only use this if \code{daylight} is nonzero.
4659
\end{datadesc}
4760

48-
4961
\begin{funcdesc}{asctime}{tuple}
5062
Convert a tuple representing a time as returned by \code{gmtime()} or
5163
\code{localtime()} to a 24-character string of the following form:
5264
\code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of
5365
the same name, there is no trailing newline.
5466
\end{funcdesc}
5567

56-
5768
\begin{funcdesc}{clock}{}
5869
Return the current CPU time as a floating point number expressed in
5970
seconds. The precision, and in fact the very definiton of the meaning
6071
of ``CPU time'', depends on that of the C function of the same name.
6172
\end{funcdesc}
6273

63-
6474
\begin{funcdesc}{ctime}{secs}
6575
Convert a time expressed in seconds since the epoch to a string
6676
representing local time. \code{ctime(t)} is equivalent to
@@ -72,11 +82,9 @@ \section{Built-in Module \sectcode{time}}
7282
\end{datadesc}
7383

7484
\begin{funcdesc}{gmtime}{secs}
75-
Convert a time expressed in seconds since the epoch to a tuple of 9
76-
integers, in UTC: year (e.g.\ 1993), month (1--12), day (1--31), hour
77-
(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
78-
Julian day (1--366), dst flag (always zero). Fractions of a second are
79-
ignored. Note subtle differences with the C function of this name.
85+
Convert a time expressed in seconds since the epoch to a time tuple
86+
in UTC in which the dst flag is always zero. Fractions of a second are
87+
ignored.
8088
\end{funcdesc}
8189

8290
\begin{funcdesc}{localtime}{secs}
@@ -86,7 +94,9 @@ \section{Built-in Module \sectcode{time}}
8694

8795
\begin{funcdesc}{mktime}{tuple}
8896
This is the inverse function of \code{localtime}. Its argument is the
89-
full 9-tuple (since the dst flag is needed). It returns a floating
97+
full 9-tuple (since the dst flag is needed --- pass -1 as the dst flag if
98+
it is unknown) which expresses the time
99+
in \em{local} time, not UTC. It returns a floating
90100
point number, for compatibility with \code{time.time()}. If the input
91101
value can't be represented as a valid time, OverflowError is raised.
92102
\end{funcdesc}
@@ -99,8 +109,75 @@ \section{Built-in Module \sectcode{time}}
99109
\begin{funcdesc}{strftime}{format, tuple}
100110
Convert a tuple representing a time as returned by \code{gmtime()} or
101111
\code{localtime()} to a string as specified by the format argument.
102-
See the \code{strftime(3)} man page for details of the syntax of
103-
format strings.
112+
113+
The following directives, shown without the optional field width and
114+
precision specification, are replaced by the indicated characters:
115+
116+
\begin{tabular}{lp{25em}}
117+
\%a & Locale's abbreviated weekday name. \\
118+
\%A & Locale's full weekday name. \\
119+
\%b & Locale's abbreviated month name. \\
120+
\%B & Locale's full month name. \\
121+
\%c & Locale's appropriate date and time representation. \\
122+
\%d & Day of the month as a decimal number [01,31]. \\
123+
\%E & Locale's combined Emperor/Era name and year. \\
124+
\%H & Hour (24-hour clock) as a decimal number [00,23]. \\
125+
\%I & Hour (12-hour clock) as a decimal number [01,12]. \\
126+
\%j & Day of the year as a decimal number [001,366]. \\
127+
\%m & Month as a decimal number [01,12]. \\
128+
\%M & Minute as a decimal number [00,59]. \\
129+
\%n & New-line character. \\
130+
\%N & Locale's Emperor/Era name. \\
131+
\%o & Locale's Emperor/Era year. \\
132+
\%p & Locale's equivalent of either AM or PM. \\
133+
\%S & Second as a decimal number [00,61]. \\
134+
\%t & Tab character. \\
135+
\%U & Week number of the year (Sunday as the first day of the
136+
week) as a decimal number [00,53]. All days in a new
137+
year preceding the first Sunday are considered to be in
138+
week 0. \\
139+
\%w & Weekday as a decimal number [0(Sunday),6]. \\
140+
\%W & Week number of the year (Monday as the first day of the
141+
week) as a decimal number [00,53]. All days in a new
142+
year preceding the first Sunday are considered to be in
143+
week 0. \\
144+
\%x & Locale's appropriate date representation. \\
145+
\%X & Locale's appropriate time representation. \\
146+
\%y & Year without century as a decimal number [00,99]. \\
147+
\%Y & Year with century as a decimal number. \\
148+
\%Z & Time zone name (or by no characters if no time zone
149+
exists). \\
150+
\%\% & \% \\
151+
\end{tabular}
152+
153+
An optional field width and precision specification can immediately
154+
follow the initial \% of a directive in the following order: \\
155+
156+
\begin{tabular}{lp{25em}}
157+
[-|0]w & the decimal digit string w specifies a minimum field
158+
width in which the result of the conversion is right-
159+
or left-justified. It is right-justified (with space
160+
padding) by default. If the optional flag `-' is
161+
specified, it is left-justified with space padding on
162+
the right. If the optional flag `0' is specified, it
163+
is right-justified and padded with zeros on the left. \\
164+
.p & the decimal digit string p specifies the minimum number
165+
of digits to appear for the d, H, I, j, m, M, o, S, U,
166+
w, W, y and Y directives, and the maximum number of
167+
characters to be used from the a, A, b, B, c, D, E, F,
168+
h, n, N, p, r, t, T, x, X, z, Z, and % directives. In
169+
the first case, if a directive supplies fewer digits
170+
than specified by the precision, it will be expanded
171+
with leading zeros. In the second case, if a directive
172+
supplies more characters than specified by the
173+
precision, excess characters will truncated on the
174+
right.
175+
\end{tabular}
176+
177+
If no field width or precision is specified for a d, H, I, m, M, S, U,
178+
W, y, or j directive, a default of .2 is used for all but j for which
179+
.3 is used.
180+
104181
\end{funcdesc}
105182

106183
\begin{funcdesc}{time}{}
@@ -121,3 +198,4 @@ \section{Built-in Module \sectcode{time}}
121198
timezone, the second is the name of the local DST timezone. If no DST
122199
timezone is defined, the second string should not be used.
123200
\end{datadesc}
201+

‎Doc/libtime.tex‎

Lines changed: 89 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,19 @@ \section{Built-in Module \sectcode{time}}
3232
E.g.\ on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
3333
second, and on the Mac, times are only accurate to whole seconds.
3434

35+
\item
36+
The time tuple as returned by \code{gmtime()} and \code{localtime()},
37+
or as accpted by \code{mktime()} is a tuple of 9
38+
integers: year (e.g.\ 1993), month (1--12), day (1--31), hour
39+
(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
40+
Julian day (1--366) and daylight savings flag (-1, 0 or 1).
41+
Note that unlike the C structure, the month value is a range of 1-12, not
42+
0-11. A year value of $<$ 100 will typically be silently converted to
43+
1900 $+$ year value. A -1 argument as daylight savings flag, passed to
44+
\code{mktime()} will usually result in the correct daylight savings
45+
state to be filled in.
46+
47+
3548
\end{itemize}
3649

3750
The module defines the following functions and data items:
@@ -45,22 +58,19 @@ \section{Built-in Module \sectcode{time}}
4558
Only use this if \code{daylight} is nonzero.
4659
\end{datadesc}
4760

48-
4961
\begin{funcdesc}{asctime}{tuple}
5062
Convert a tuple representing a time as returned by \code{gmtime()} or
5163
\code{localtime()} to a 24-character string of the following form:
5264
\code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of
5365
the same name, there is no trailing newline.
5466
\end{funcdesc}
5567

56-
5768
\begin{funcdesc}{clock}{}
5869
Return the current CPU time as a floating point number expressed in
5970
seconds. The precision, and in fact the very definiton of the meaning
6071
of ``CPU time'', depends on that of the C function of the same name.
6172
\end{funcdesc}
6273

63-
6474
\begin{funcdesc}{ctime}{secs}
6575
Convert a time expressed in seconds since the epoch to a string
6676
representing local time. \code{ctime(t)} is equivalent to
@@ -72,11 +82,9 @@ \section{Built-in Module \sectcode{time}}
7282
\end{datadesc}
7383

7484
\begin{funcdesc}{gmtime}{secs}
75-
Convert a time expressed in seconds since the epoch to a tuple of 9
76-
integers, in UTC: year (e.g.\ 1993), month (1--12), day (1--31), hour
77-
(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
78-
Julian day (1--366), dst flag (always zero). Fractions of a second are
79-
ignored. Note subtle differences with the C function of this name.
85+
Convert a time expressed in seconds since the epoch to a time tuple
86+
in UTC in which the dst flag is always zero. Fractions of a second are
87+
ignored.
8088
\end{funcdesc}
8189

8290
\begin{funcdesc}{localtime}{secs}
@@ -86,7 +94,9 @@ \section{Built-in Module \sectcode{time}}
8694

8795
\begin{funcdesc}{mktime}{tuple}
8896
This is the inverse function of \code{localtime}. Its argument is the
89-
full 9-tuple (since the dst flag is needed). It returns a floating
97+
full 9-tuple (since the dst flag is needed --- pass -1 as the dst flag if
98+
it is unknown) which expresses the time
99+
in \em{local} time, not UTC. It returns a floating
90100
point number, for compatibility with \code{time.time()}. If the input
91101
value can't be represented as a valid time, OverflowError is raised.
92102
\end{funcdesc}
@@ -99,8 +109,75 @@ \section{Built-in Module \sectcode{time}}
99109
\begin{funcdesc}{strftime}{format, tuple}
100110
Convert a tuple representing a time as returned by \code{gmtime()} or
101111
\code{localtime()} to a string as specified by the format argument.
102-
See the \code{strftime(3)} man page for details of the syntax of
103-
format strings.
112+
113+
The following directives, shown without the optional field width and
114+
precision specification, are replaced by the indicated characters:
115+
116+
\begin{tabular}{lp{25em}}
117+
\%a & Locale's abbreviated weekday name. \\
118+
\%A & Locale's full weekday name. \\
119+
\%b & Locale's abbreviated month name. \\
120+
\%B & Locale's full month name. \\
121+
\%c & Locale's appropriate date and time representation. \\
122+
\%d & Day of the month as a decimal number [01,31]. \\
123+
\%E & Locale's combined Emperor/Era name and year. \\
124+
\%H & Hour (24-hour clock) as a decimal number [00,23]. \\
125+
\%I & Hour (12-hour clock) as a decimal number [01,12]. \\
126+
\%j & Day of the year as a decimal number [001,366]. \\
127+
\%m & Month as a decimal number [01,12]. \\
128+
\%M & Minute as a decimal number [00,59]. \\
129+
\%n & New-line character. \\
130+
\%N & Locale's Emperor/Era name. \\
131+
\%o & Locale's Emperor/Era year. \\
132+
\%p & Locale's equivalent of either AM or PM. \\
133+
\%S & Second as a decimal number [00,61]. \\
134+
\%t & Tab character. \\
135+
\%U & Week number of the year (Sunday as the first day of the
136+
week) as a decimal number [00,53]. All days in a new
137+
year preceding the first Sunday are considered to be in
138+
week 0. \\
139+
\%w & Weekday as a decimal number [0(Sunday),6]. \\
140+
\%W & Week number of the year (Monday as the first day of the
141+
week) as a decimal number [00,53]. All days in a new
142+
year preceding the first Sunday are considered to be in
143+
week 0. \\
144+
\%x & Locale's appropriate date representation. \\
145+
\%X & Locale's appropriate time representation. \\
146+
\%y & Year without century as a decimal number [00,99]. \\
147+
\%Y & Year with century as a decimal number. \\
148+
\%Z & Time zone name (or by no characters if no time zone
149+
exists). \\
150+
\%\% & \% \\
151+
\end{tabular}
152+
153+
An optional field width and precision specification can immediately
154+
follow the initial \% of a directive in the following order: \\
155+
156+
\begin{tabular}{lp{25em}}
157+
[-|0]w & the decimal digit string w specifies a minimum field
158+
width in which the result of the conversion is right-
159+
or left-justified. It is right-justified (with space
160+
padding) by default. If the optional flag `-' is
161+
specified, it is left-justified with space padding on
162+
the right. If the optional flag `0' is specified, it
163+
is right-justified and padded with zeros on the left. \\
164+
.p & the decimal digit string p specifies the minimum number
165+
of digits to appear for the d, H, I, j, m, M, o, S, U,
166+
w, W, y and Y directives, and the maximum number of
167+
characters to be used from the a, A, b, B, c, D, E, F,
168+
h, n, N, p, r, t, T, x, X, z, Z, and % directives. In
169+
the first case, if a directive supplies fewer digits
170+
than specified by the precision, it will be expanded
171+
with leading zeros. In the second case, if a directive
172+
supplies more characters than specified by the
173+
precision, excess characters will truncated on the
174+
right.
175+
\end{tabular}
176+
177+
If no field width or precision is specified for a d, H, I, m, M, S, U,
178+
W, y, or j directive, a default of .2 is used for all but j for which
179+
.3 is used.
180+
104181
\end{funcdesc}
105182

106183
\begin{funcdesc}{time}{}
@@ -121,3 +198,4 @@ \section{Built-in Module \sectcode{time}}
121198
timezone, the second is the name of the local DST timezone. If no DST
122199
timezone is defined, the second string should not be used.
123200
\end{datadesc}
201+

0 commit comments

Comments
 (0)