Re: return false if error

On Tue, Mar 18, 2014 at 2:06 PM, Robert Stoll <php@tutteli.ch> wrote: > Heya, > > We were discussing the scenario where a function returns false in an error case in a thread on > the general mailing list. > I always thought the documentation would use mixed as return type in such a situation (like in > strpos) but others > disagreed. > > For instance, Mike Ford told me: >> It has always been policy in the documentation to specify only the substantive return >> type(s) of a function >> in the signature, and only mention return of "false" as an error indicator in the >> description. There are >> many, many examples of this in the manual, and I think it's unlikely the policy will >> change any time soon. > > So my question is, what is your opinion on that topic? > > I already committed two patches to change the return type to mixed, since the functions also > return false. > I could revert them (or discard the commit, I do not know if this is possible - was made > through edit.php.net). > > IMO the most important thing is that the documentation is consistent. Either change all such > functions to mixed or > change strpos to int (and probably further functions as well). > Or we go a new path and add a construct which indicates that a function returns false as well. > > For instance: > > int! strpos ( string $haystack , mixed $needle [, int $offset = 0 ] ) > > where int! stands for int or false if an error occurs. Interesting. I don't know why or when strpos docs got changed to 'mixed', that definitely is not how it was originally: http://www.php.net/manual/en/about.prototypes.php The docs consistently white-lie with "on failure" return value, for example; if you pass 10 arguments to strpos() it will not return false, it will actually return null. This is true for ~98% of the documented functions. And we don't have the return type 'mixed' everywhere. I believe we always document the return value of a successful execution of the function, then mention "but on failure it can be blabla". A successful case can also be a "failure value" (such as not-found-but-that-doesn't-really-matter) - so the strpos() case is very 50/50 if it should be int or mixed. Your int! idea seems interesting. But its not always that a function returns false on "successful execution of the function, but didn't find what you wanted".. What happens in that case? -Hannes