Doc #73839 [NEW]: suggestion to improve clarity of functions to use for queue / stack behavior

From: pjvleeuwen at gmail dot com Operating system: n/a PHP version: 7.1.0 Package: Arrays related Bug Type: Documentation Problem Bug description:suggestion to improve clarity of functions to use for queue / stack behavior Description: ------------ For background see: http://stackoverflow.com/questions/41387092/php-pop-push-shift-unshift-which-to-use-for-queues-and-which-for-stacks/41387093#41387093 Currently as a new(ish) PHP developer the documentation left some unclarity for me on how to use stacks and queues. The documentation on the array_push(), array_pop(), array_shift() and array_unshift() functions could more clearly describe there typical usage when dealing with queues and stacks. Based on performance I would expect that the advisable usage would be: for stacks use push & pop ; for queues use push & shift. Please let me know if this is an incorrect usage. My suggestions below are based on those assumptions. Either way the documentation could be improved by giving some more clarity, so if my assumptions were incorrect, then please still take the suggestions below and modify where appropriate. I would propose to dedicate one sentence on this for each function in the description and update the examples accordingly. In the description of array_push() change: "array_push() treats array as a stack" to: "array_push() treats array as a stack (along with array_pop()) or queue (along with array_shift())" In the description of array_pop() add: "Use array_pop() along with array_push() to treat the array as stack." In the description of array_shift() add: "Use array_shift() along with array_push() to treat the array as queue." In the description of array_unshift() add: "Note: to treat the array as typical queue or stack, consider using other methods, see array_push() for pointers." In the example of array_shift() change the variable name from "$stack" to "$queue". In the example of array_unshift() change the variable name from "$queue" to "$array". Possibly also update the descriptions in the 'see also' section accordingly for added clarity. -- Edit bug report at https://bugs.php.net/bug.php?id=73839&edit=1 -- Try a snapshot (PHP 5.4): https://bugs.php.net/fix.php?id=73839&r=trysnapshot54 Try a snapshot (PHP 5.5): https://bugs.php.net/fix.php?id=73839&r=trysnapshot55 Try a snapshot (trunk): https://bugs.php.net/fix.php?id=73839&r=trysnapshottrunk Fixed in SVN: https://bugs.php.net/fix.php?id=73839&r=fixed Fixed in release: https://bugs.php.net/fix.php?id=73839&r=alreadyfixed Need backtrace: https://bugs.php.net/fix.php?id=73839&r=needtrace Need Reproduce Script: https://bugs.php.net/fix.php?id=73839&r=needscript Try newer version: https://bugs.php.net/fix.php?id=73839&r=oldversion Not developer issue: https://bugs.php.net/fix.php?id=73839&r=support Expected behavior: https://bugs.php.net/fix.php?id=73839&r=notwrong Not enough info: https://bugs.php.net/fix.php?id=73839&r=notenoughinfo Submitted twice: https://bugs.php.net/fix.php?id=73839&r=submittedtwice register_globals: https://bugs.php.net/fix.php?id=73839&r=globals PHP 4 support discontinued: https://bugs.php.net/fix.php?id=73839&r=php4 Daylight Savings: https://bugs.php.net/fix.php?id=73839&r=dst IIS Stability: https://bugs.php.net/fix.php?id=73839&r=isapi Install GNU Sed: https://bugs.php.net/fix.php?id=73839&r=gnused Floating point limitations: https://bugs.php.net/fix.php?id=73839&r=float No Zend Extensions: https://bugs.php.net/fix.php?id=73839&r=nozend MySQL Configuration Error: https://bugs.php.net/fix.php?id=73839&r=mysqlcfg