Re: ext/mysql return types

On Tue, 04 Jul 2006, Nuno Lopes wrote: > The answer to your questions are answered in our howto. Mainly here: > http://doc.php.net/php/dochowto/chapter-conventions.php > > Quoting the important part (for now): > "Do not use mixed, if the return value is of a certain (not boolean) type, > and FALSE only on error. Provide the primary return type as the return type > of the function, and write down in the explanation, that it returns FALSE > on error. Use &return.success; if the function returns TRUE on success, and > FALSE on failure. " Oh, okay. Seems I missed this part. So 2) '"mixed" return values on error paths" is clearly a "no". But what about 1) '"mixed" return values in normal usage', for example mysql_query(), which may return TRUE in normal usage? Or mysql_fetch_array() which returns FALSE if there are no more rows -- should this be considered an error condition? At least the mysql_query() issue confused someone on IRC today. (Besides this, I still consider my corrections 3) as valid.) Kind regards, Horst > ----- Original Message ----- > >Hi, > > > >I just noticed that the return types of some ext/mysql functions are not > >correct, or at least misleading. > > > > > >1) "mixed" return values in normal usage > >---------------------------------------- > > > >In the description of mysql_query(), the interface is shown as > >follows: > > > >resource mysql_query ( string query [, resource link_identifier] ) > > > >But the "Return Values" section makes clear that the return type could > >also be a boolean; shouldn't the return type be "mixed" instead of > >"resource", as for example in the documentation to mysqli_query() -- or > >has this been documented this way for a reason? > > > >All ext/mysql functions which return mixed types but are not > >properly documented to do so: > >* mysql_query > >* mysql_db_query > >* mysql_fetch_array > >* mysql_fetch_assoc > >* mysql_fetch_field (here the docs even lack "or FALSE if there are no > > more rows" in the "Return Values" section) > >* mysql_fetch_object > >* mysql_fetch_row > >* mysql_unbuffered_query > > > > > >2) "mixed" return values on error paths > >--------------------------------------- > > > >Similarly this is true for mysql_connect(), although here FALSE is only > >returned on failure; the "normal" return type is "resource". Is this > >intentional, or should it also be corrected to "mixed"? (I'd vote for > >the former.) > > > >All ext/mysql functions which return FALSE on failure but are not > >documented to do so in the "Description": > >mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags, > >mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type, > >mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info, > >mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields, > >mysql_list_processes, mysql_list_tables, mysql_num_fields, > >mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result, > >mysql_stat (returns NULL on failure, not FALSE), mysql_tablename, > >mysql_thread_id. > > > > > >3) minor corrections > >-------------------- > > > >Beyond this, > >* mysql_field_seek needs a "Return Values" section (although it is > > intuitive that it returns TRUE on success and FALSE on failure). > >* mysql_field_table and mysql_field_type need "returns FALSE on failure" > > to be documented. > > > > > >Any comments/objections to these corrections? If nobody vetoes, I would > >starting to fix 1) and 3) the next days. > > > >Kind regards, > >Horst -- PGP-Key 0xD40E0E7A