From 21be14709429fb6d6bcac37163930f934a51737e Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Thu, 12 Dec 1996 17:59:37 +0000 Subject: 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. --- Doc/lib/libtime.tex | 49 +++++++++++++++++-------------------------------- Doc/libtime.tex | 49 +++++++++++++++++-------------------------------- 2 files changed, 34 insertions(+), 64 deletions(-) diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex index 7c52f7c..bc83f03 100644 --- a/Doc/lib/libtime.tex +++ b/Doc/lib/libtime.tex @@ -33,6 +33,14 @@ 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 \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 @@ the same name, there is no trailing newline. \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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or \%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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or \%\% & \% \\ \end{tabular} - An optional field width and precision specification can immediately - follow the initial \% of a directive in the following order: \\ - -\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} + Additional directives may be supported on certain platforms, but + only the ones listed here have a meaning standardized by ANSI C. - 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} 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 @@ 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 \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 @@ the same name, there is no trailing newline. \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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or \%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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or \%\% & \% \\ \end{tabular} - An optional field width and precision specification can immediately - follow the initial \% of a directive in the following order: \\ - -\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} + Additional directives may be supported on certain platforms, but + only the ones listed here have a meaning standardized by ANSI C. - 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} -- cgit v0.12