MySQL Bugs: #36814: mysql monitor help documentation does not match time

Bug #36814	mysql monitor help documentation does not match time_format() behaviour
Submitted:	20 May 2008 9:02	Modified:	14 May 2009 0:42
Reporter:	Janek Bogucki	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.0.51a-3ubuntu5.1-log, 5.0.60	OS:	Linux (Kubuntu 8.04)
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
The help content for time_format indicates the microseconds format code (%f) will output NULL or 0. It does not, instead the supplied microseconds value is output, which is more useful than the documented behaviour.

mysql> help time_format
Name: 'TIME_FORMAT'
Description:
Syntax:
TIME_FORMAT(time,format)

This is used like the DATE_FORMAT() function, but the format string may
contain format specifiers only for hours, minutes, and seconds. Other
specifiers produce a NULL value or 0.

URL: http://dev.mysql.com/doc/refman/5.0/en/date-and-time-functions.html

Examples:
mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l');
        -> '100 100 04 04 4'

mysql> select time_format('100:00:00.5', '%H hours %h minutes %I seconds and %f ms');
+------------------------------------------------------------------------+
| time_format('100:00:00.5', '%H hours %h minutes %I seconds and %f ms') |
+------------------------------------------------------------------------+
| 100 hours 04 minutes 04 seconds and 500000 ms                          |
+------------------------------------------------------------------------+
1 row in set (0.00 sec)

How to repeat:
Read the documentation for help time_format then enter

select time_format('100:00:00.123555', '%f');

Suggested fix:
Correct the output of help time_format.

Thank you for a problem report. Verified with 5.0.60 also:

C:\Program Files\MySQL\MySQL Server 5.0\bin>mysql -uroot -proot test -P3308
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.0.60-enterprise-gpl-nt-log MySQL Enterprise Server (GPL)

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> help time_format
Name: 'TIME_FORMAT'
Description:
Syntax:
TIME_FORMAT(time,format)

This is used like the DATE_FORMAT() function, but the format string may
contain format specifiers only for hours, minutes, and seconds. Other
specifiers produce a NULL value or 0.
Examples:
mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l');
        -> '100 100 04 04 4'

mysql> select time_format('10:00:01.25', '%H %h %I and %f ms');
+--------------------------------------------------+
| time_format('10:00:01.25', '%H %h %I and %f ms') |
+--------------------------------------------------+
| 10 10 10 and 250000 ms                           |
+--------------------------------------------------+
1 row in set (0.00 sec)

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.