> > I am not sure that this is purely a problem with the documentation. > > It seems possible to me that someone updated the documentation to > reflect a > > new intention for these functions. > > Will it not be that these functions will be altered in the core to do > what > > the documentation says? > > If the docs are not correct, we cannot simply change the source to > conform for BC reasons. > > In this case, see <https://github.com/php/doc-en/issues/3629>. >
I can appreciate that. Going forward, is there any benefit to preserving the behavior of returning integers beyond -1, 0, and 1? Should these topically related functions receive a new last argument? bool $distance = false I don't know if there is already an established naming convention for such a value in a function signature. This way codebases that rely on the historic behavior can set $distance as true, otherwise omit the parameter. Or is there absolutely no reason to return the calculated distance because a 3-way return is all that is ever needed? mickmackusa
