php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #73839 suggestion to improve clarity of functions to use for queue / stack behavior
Submitted: 2016-12-29 21:26 UTC Modified: 2021-05-28 14:45 UTC
From: pjvleeuwen at gmail dot com Assigned: cmb (profile)
Status: Not a bug Package: Arrays related
PHP Version: 7.1.0 OS: n/a
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: pjvleeuwen at gmail dot com
New email:
PHP Version: OS:

 

 [2016-12-29 21:26 UTC] pjvleeuwen at gmail dot com
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.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2021-05-28 14:45 UTC] cmb@php.net
-Status: Open +Status: Not a bug -Assigned To: +Assigned To: cmb
 [2021-05-28 14:45 UTC] cmb@php.net
Changing the parameter names would constitute a BC break as of PHP
8.0.0, so is likely not an option.  Using array_push() and
array_pop() as typical stack operations isn't particularly
noteworthy, since these are common primitives for stacks (still,
it is already mentioned in the function description).  Using array
as queues is possible, and generally it doesn't matter whether you
use array_push()/array_shift() or array_pop()/array_unshift(), but
either case isn't particularly efficient.  SplQueue might be
preferable for queues.  Anyhow, since PHP arrays are multi-purpose
data structures, it's not quite as simple as this.  I think we
don't want to go down the rabbit hole of categorizing these
functions as treating the array as stack/queue.
 
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Wed Jun 23 09:01:24 2021 UTC