Added remark about time() and sleep()'s subsecond precision.
Added hint about using clock() for benchmarks etc.
Removed non-portable strftime directives and field width, and added a
warning about non-standard features.
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index 7c52f7c..bc83f03 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -33,6 +33,14 @@
second, and on the Mac, times are only accurate to whole seconds.
\item
+On the other hand, the precision of \code{time()} and \code{sleep()}
+is better than their UNIX equivalents: times are expressed as floating
+point numbers, \code{time()} returns the most accurate time available
+(using UNIX \code{gettimeofday()} where available), and \code{sleep()}
+will accept a time with a nonzero fraction (UNIX \code{select()} is
+used to implement this, where available).
+
+\item
The time tuple as returned by \code{gmtime()} and \code{localtime()},
or as accpted by \code{mktime()} is a tuple of 9
integers: year (e.g.\ 1993), month (1--12), day (1--31), hour
@@ -68,7 +76,9 @@
\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'', depends on that of the C function of the same name.
+of ``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 Python
+or timing algorithms.
\end{funcdesc}
\begin{funcdesc}{ctime}{secs}
@@ -120,18 +130,13 @@
\%B & Locale's full month name. \\
\%c & Locale's appropriate date and time representation. \\
\%d & Day of the month as a decimal number [01,31]. \\
- \%E & Locale's combined Emperor/Era name and year. \\
\%H & Hour (24-hour clock) as a decimal number [00,23]. \\
\%I & Hour (12-hour clock) as a decimal number [01,12]. \\
\%j & Day of the year as a decimal number [001,366]. \\
\%m & Month as a decimal number [01,12]. \\
\%M & Minute as a decimal number [00,59]. \\
- \%n & New-line character. \\
- \%N & Locale's Emperor/Era name. \\
- \%o & Locale's Emperor/Era year. \\
\%p & Locale's equivalent of either AM or PM. \\
\%S & Second as a decimal number [00,61]. \\
- \%t & Tab character. \\
\%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
@@ -150,33 +155,13 @@
\%\% & \% \\
\end{tabular}
- An optional field width and precision specification can immediately
- follow the initial \% of a directive in the following order: \\
+ Additional directives may be supported on certain platforms, but
+ only the ones listed here have a meaning standardized by ANSI C.
-\begin{tabular}{lp{25em}}
- [-|0]w & the decimal digit string w specifies a minimum field
- width in which the result of the conversion is right-
- or left-justified. It is right-justified (with space
- padding) by default. If the optional flag `-' is
- specified, it is left-justified with space padding on
- the right. If the optional flag `0' is specified, it
- is right-justified and padded with zeros on the left. \\
- .p & the decimal digit string p specifies the minimum number
- of digits to appear for the d, H, I, j, m, M, o, S, U,
- w, W, y and Y directives, and the maximum number of
- characters to be used from the a, A, b, B, c, D, E, F,
- h, n, N, p, r, t, T, x, X, z, Z, and % directives. In
- the first case, if a directive supplies fewer digits
- than specified by the precision, it will be expanded
- with leading zeros. In the second case, if a directive
- supplies more characters than specified by the
- precision, excess characters will truncated on the
- right.
-\end{tabular}
-
- If no field width or precision is specified for a d, H, I, m, M, S, U,
- W, y, or j directive, a default of .2 is used for all but j for which
- .3 is used.
+ On some platforms, an optional field width and precision
+ specification can immediately follow the initial \% of a
+ directive in the following order; this is also not portable.
+ The field width is normally 2 except for \%j where it is 3.
\end{funcdesc}