Doc #74942 [Opn]: Slight Ambiguity in Definition of Return Value

Edit report at https://bugs.php.net/bug.php?id=74942&edit=1 ID: 74942 User updated by: derek dot price at dxc dot com Reported by: derek dot price at dxc dot com Summary: Slight Ambiguity in Definition of Return Value Status: Open Type: Documentation Problem Package: Documentation problem Operating System: All PHP Version: 7.1.7 Block user comment: N Private report: N New Comment: In English, "in any of" can be read as "in any one of". Even though it is the rarer interpretation, since the alternative reading inverts the meaning of the statement, this is ambiguous. Now that you mention it, I'll agree that the word "missing" is awkward here as well. How about, "Returns an array containing all the entries from array1 whose keys are absent from all of the other arrays." Also, please include the three-argument example that I submitted in the doc. That removes all possible ambiguity through demonstration. Thanks and regards. Previous Comments: ------------------------------------------------------------------------ [2017-07-18 12:08:22] peehaa@php.net Nothing is missing in the other arrays. They are just not in it. Also imo the current wording is not ambiguous. And I am tempted to close as "not a bug" but I will leave it open to see what others have to say about it. ------------------------------------------------------------------------ [2017-07-17 18:28:24] derek dot price at dxc dot com Description: ------------ --- From manual page: http://www.php.net/function.array-diff-key --- The return value is specified as "Returns an array containing all the entries from array1 whose keys are not present in any of the other arrays." On my first read, I interpreted this as how the function actually works, as revealed by testing. However, I got in an argument with a developer who read this to mean something different, almost the opposite, a meaning I could see in the original text once pointed out. Basically, the other developer had interpreted this as, "Returns an array containing all the entries from array1 whose keys is not present in AT LEAST ONE of the other arrays". Whereas, the actual behavior can more precisely be stated as, "Returns an array containing all the entries from array1 whose keys are MISSING FROM ALL of the other arrays." A three argument example like the one I entered as the test script & expected result, below, would probably help too. Test script: --------------- <?php $array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4); $array2 = array('green' => 5, 'yellow' => 7, 'cyan' => 8); $array3 = array('blue' => 6, 'yellow' => 7, 'mauve' => 8); var_dump(array_diff_key($array1, $array2, $array3)); Expected result: ---------------- array(2) { ["red"]=> int(2) ["purple"]=> int(4) } ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=74942&edit=1