Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
rfc:array_part [2012/05/14 10:36] – [Specification for the function] cataphract | rfc:array_part [2012/05/21 17:29] – no recursion prohibition cataphract |
---|
====== Request for Comments: array_part ====== | ====== Request for Comments: array_part ====== |
* Version: 1.0 | * Version: 1.1 |
* Date: 2012-05-14 | * Date: 2012-05-14 |
* Author: Gustavo Lopes <cataphract@php.net> | * Author: Gustavo Lopes <cataphract@php.net> |
An index //i// has the following meaning: | An index //i// has the following meaning: |
* If ''$indexesAreKeys'' is ''false'' and //i// is a non-negative integer (possibly after casting) then an element is at index //i// if it //i// is the the number of times one would have to call ''next()'' after calling ''reset()'' for ''current()'' to return that element. | * If ''$indexesAreKeys'' is ''false'' and //i// is a non-negative integer (possibly after casting) then an element is at index //i// if it //i// is the the number of times one would have to call ''next()'' after calling ''reset()'' for ''current()'' to return that element. |
* If ''$indexesAreKeys'' is ''false'' and //i// is a negative number, then an element is at positive //i// if //-i+1// is the number of times one would have to call ''prev()'' after calling ''end()'' for ''current()'' to return that element. | * If ''$indexesAreKeys'' is ''false'' and //i// is a negative integer, then an element is at index //i// if //-i-1// is the number of times one would have to call ''prev()'' after calling ''end()'' for ''current()'' to return that element. |
* If ''$indexesAreKeys'' is ''true'' then an element is at //i// if its array key is //i//. | * If ''$indexesAreKeys'' is ''true'' then an element is at //i// if its array key is //i//. |
| |
| The keys in the original array are not preserved in the output, expect at levels that were not visited. References are preserved. |
| |
This function shall return ''false'' upon finding error conditions. The following are error conditions: | This function shall return ''false'' upon finding error conditions. The following are error conditions: |
* Giving malformed part specifications (where the individual elements do not follow the syntactic rules given here). | * Giving malformed part specifications (where the individual elements do not follow the syntactic rules given here). |
* Specifying an part index than does not exist at at least of the elements at the level the part refers to: (e.g. ''%%array_part([[1],[1,2]], [['start'=>0, 'end'=>-1], 1])%%'' is an error condition, because while ''1'' is a valid index for ''%%[1,2]%%'', it is not so for ''%%[[1]]%%''). However, span part specifications that comprise all elements are always accepted. | * Specifying an part index than does not exist at at least of the elements at the level the part refers to: (e.g. ''%%array_part([[1],[1,2]], [['start'=>0, 'end'=>-1], 1])%%'' is an error condition, because while ''1'' is a valid index for ''%%[1,2]%%'', it is not so for ''%%[[1]]%%''). However, span part specifications that comprise all elements are always accepted. |
* Giving a part specification with levels that do not exist in the input. This does not apply if, as a result of a span part that comprises all the elements of that level and at the level before existing only empty arrays, no elements were left for the next element. For instance '%%array_part({}, [['start'=>0, 'end'=>-1]])%%' is valid, as is '%%array_part([[]], [0, ['start'=>0, 'end'=>-1], 1, 2, 3])%%', which will return ''%%[[]]%%''. | * Giving a part specification with levels that do not exist in the input. This does not apply if, as a result of a span part that comprises all the elements of that level and at the level before existed only empty arrays, no elements were left for the next level. For instance '%%array_part([], [['start'=>0, 'end'=>-1]])%%' is valid, as is '%%array_part([[]], [0, ['start'=>0, 'end'=>-1], 1, 2, 3])%%', which will return ''%%[[]]%%''. |
* Encountering already visited array elements from the original array (recursion). | |
| |
===== Sample implementation and usage ===== | ===== Proposed implementation ===== |
| |
| The proposed implementation is available as [[https://github.com/cataphract/php-src/tree/array_part|git branch on github]]. I'll update the branch it as I improve it. This is not a prototype. If this proposal is accepted, this implementation will be merged. |
| |
| ===== Sample PHP implementation and usage ===== |
| |
A sample implementation, with tests exemplifying the use of this function, [[https://gist.github.com/2660601|is available]]. | A sample implementation, with tests exemplifying the use of this function, [[https://gist.github.com/2660601|is available]]. |
| |
| This implementation differs in some respects to the internal implementation with respect to behavior. Its purpose is only to exemplify the usage of the function here proposed. |
| |
[[https://gist.github.com/2660601#file_test.php|Direct link to the tests]] | [[https://gist.github.com/2660601#file_test.php|Direct link to the tests]] |
| |
* 2012-05-14 Initial version | * 2012-05-14 Initial version |
| * 2012-05-21 Dropped recursion restriction, added note on how references are preserved, added link to native implementation |
| |
| |
| |