Doc #74942 [Asn->Csd]: Slight Ambiguity in Definition of Return Value

Edit report at https://bugs.php.net/bug.php?id=74942&edit=1 ID: 74942 Updated by: peehaa@php.net Reported by: derek dot price at dxc dot com Summary: Slight Ambiguity in Definition of Return Value -Status: Assigned +Status: Closed Type: Documentation Problem Package: Documentation problem Operating System: All PHP Version: 7.1.7 Assigned To: peehaa Block user comment: N Private report: N New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2017-07-21 14:04:58] peehaa@php.net Automatic comment from SVN on behalf of peehaa Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=342691 Log: Improved wording of description and added an extra example using more arrays. #74942 -- Provided by anonymous 82010 (jay@room11.org) ------------------------------------------------------------------------ [2017-07-18 12:47:07] derek dot price at dxc dot com 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. ------------------------------------------------------------------------ [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