Doc #52778 [Bgs->Csd]: array_walk() doc contradicts itself

Edit report at http://bugs.php.net/bug.php?id=52778&edit=1 ID: 52778 Updated by: cataphract@php.net Reported by: daniel at danielnorton dot com Summary: array_walk() doc contradicts itself -Status: Bogus +Status: Closed Type: Documentation Problem Package: Documentation problem PHP Version: 5.3.3 -Assigned To: +Assigned To: cataphract Block user comment: N New Comment: The note is very clear: "needs to be working with the actual values of the array". "values" as technical meaning here, in the sense arrays are made of "elements", each one a "key"/"value" pair. In unset($my_array[10]), you're not changing a value, you're removing an element. I agree that "may not change the array itself" *could* be ambiguous, but it's immediately qualified with "e.g. add/delete elements, unset elements". Anyway, to clear the confusing, I've committed revision #303045. Previous Comments: ------------------------------------------------------------------------ [2010-09-05 07:26:31] cataphract@php.net Automatic comment from SVN on behalf of cataphract Revision: http://svn.php.net/viewvc/?view=revision&revision=303045 Log: * Made clearer the requirements for the callback function, as per bug #52778 ------------------------------------------------------------------------ [2010-09-05 06:14:16] daniel at danielnorton dot com I am reading the phrase as written, even if not as you are reading it. Given your interpretation, I should perhaps describe the problem as an ambiguity rather than as a contradiction. We can each read different meanings because the writing is ambiguous, and it is ambiguous in two ways: 1) For elements (in the note box): A "change" to an element can include a change such as this: unset($my_array[10]); The more specific meaning that you apparently infer is that "changes" refers *only* to an element's *contents*. 2) For the array (below the note box): Just as with an element, a "change" to an array "itself" *can* include its content, but you are apparently inferring that it *excludes* changes to its content. Perhaps you are reading "itself" to mean "its structure", but there is no such specific (or general) meaning of "itself". Both inferences are reasonable. The resolution to this issue requires resolving these ambiguities. The documentation should read "change to its content" where it means only "change to its content", and "change to its structure" where it means only "change to its structure". ------------------------------------------------------------------------ [2010-09-05 05:34:45] cataphract@php.net You're not reading the whole phrase. It says "Users may not change the array itself from the callback function. e.g. Add/delete elements, unset elements, etc.". It does not contradict the note before. The note before is about changing the array data (the values), what's not possible is to change the array itself (i.e., its structure). ------------------------------------------------------------------------ [2010-09-05 01:53:44] daniel at danielnorton dot com Description: ------------ Here: http://php.net/manual/en/function.array-walk.php For the funcname parameter it mentions in a note box that specifying a parameter as a reference can be useful because "any changes made to those elements will be made in the original array itself". After the box, the description of the parameter continues with a contradictory warning: "Users may not change the array itself from the callback function." Specifying a reference is useful to save memory for large arrays, but the reason given is wrong and misleading. You should also probably take the opportunity to clarify that the reference must be in the callback function formal parameter list and not the actual parameter list of the invocation, as the latter is deprecated in PHP 5.3.0. ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/bug.php?id=52778&edit=1