rfc:cyclic-replace
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:cyclic-replace [2015/02/02 16:55] – francois | rfc:cyclic-replace [2017/09/22 13:28] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Add cyclic string replacements ====== | ====== Add cyclic string replacements ====== | ||
- | * Version: 1.6 | + | * Version: 1.7 |
* Creation date: 2015-01-05 | * Creation date: 2015-01-05 | ||
- | * Last modification date : 2015-02-02 | + | * Last modification date : 2015-04-02 |
* Author: François Laupretre, francois@tekwire.net | * Author: François Laupretre, francois@tekwire.net | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
Line 18: | Line 18: | ||
was recently revived, refined, and improved by the internals community. | was recently revived, refined, and improved by the internals community. | ||
- | In the current str_[i]replace() implementation, | + | In the current str_[i]replace() implementation, |
is supported but quite useless as, in this case, the replace array is converted to the ' | is supported but quite useless as, in this case, the replace array is converted to the ' | ||
string and, then, string/ | string and, then, string/ | ||
Line 24: | Line 24: | ||
This RFC proposes that, in this case, the first occurence of search is replaced with | This RFC proposes that, in this case, the first occurence of search is replaced with | ||
the first element of the replace array, the second occurence with the second | the first element of the replace array, the second occurence with the second | ||
- | element, and so on. When we arrive at the end of the replace array, | + | element, and so on. When we arrive at the end of the replace array, it loops |
- | behaviors can be chosen (loop, repeat last element, etc... see the | + | to the first element, and so on. |
- | //options// parameter below). | + | |
- | + | ||
- | This is what we name ' | + | |
- | only when we set the option | + | |
Note that replacements are done in array order. Key values are ignored in replace arrays. | Note that replacements are done in array order. Key values are ignored in replace arrays. | ||
Line 44: | Line 40: | ||
' | ' | ||
- | Arbitrarily nested subject arrays are now supported, returning exactly the same | + | Other feature : Arbitrarily nested subject arrays are now supported, returning exactly the same |
array structure and preserving keys. Only values are replaced. | array structure and preserving keys. Only values are replaced. | ||
Line 53: | Line 49: | ||
===== Backward Incompatible Changes ===== | ===== Backward Incompatible Changes ===== | ||
- | |||
- | ==== C API ==== | ||
- | |||
- | php_char_to_str_ex() and php_str_to_str_ex() (defined in ext/ | ||
- | take an additional //options// | ||
- | argument. This argument is not used at the moment but it allows their API | ||
- | to remain compatible with the new new php_str_to_array_ex() function. | ||
- | |||
- | Note that the API for php_char_to_str() and php_str_to_str() is not modified. | ||
==== PHP API ==== | ==== PHP API ==== | ||
Line 81: | Line 68: | ||
All these BC breaks are similar and deal with array to string conversions in | All these BC breaks are similar and deal with array to string conversions in | ||
- | previous implementations. | + | previous implementations. |
relying on an array-to-string conversion (with E_NOTICE) when calling these | relying on an array-to-string conversion (with E_NOTICE) when calling these | ||
functions, while theoritically supported, is very improbable. | functions, while theoritically supported, is very improbable. | ||
Line 96: | Line 83: | ||
==== To Existing Extensions ==== | ==== To Existing Extensions ==== | ||
- | Extensions using one of the C functions with a modified API (see BC changes in C API above) | + | None |
- | need to be adapted (adding a 0 final argument to each call). Only two occurences of such calls exist in | + | |
- | the whole php-src tree (outside of string.c). | + | |
==== To Opcache ==== | ==== To Opcache ==== | ||
Line 106: | Line 91: | ||
==== New Constants ==== | ==== New Constants ==== | ||
- | === C constants === | + | None |
- | + | ||
- | These new C constants are defined in ext/ | + | |
- | + | ||
- | * PHP_STR_ARRAY_REPLACE_STOP | + | |
- | * PHP_STR_ARRAY_REPLACE_FIRST | + | |
- | * PHP_STR_ARRAY_REPLACE_LAST | + | |
- | * PHP_STR_ARRAY_REPLACE_LOOP | + | |
- | * PHP_STR_ARRAY_REPLACE_EMPTY | + | |
- | * PHP_STR_ARRAY_REPLACE_MASK | + | |
- | * PHP_STR_ARRAY_REPLACE_MAX | + | |
- | * PHP_REPLACE_MASK | + | |
- | + | ||
- | === PHP constants === | + | |
- | + | ||
- | New constants are defined to allow controlling how the replacements are | + | |
- | done after a replace array is exhausted (when there are more occurences | + | |
- | of search in the subject than the number of elements in the replace array). These constants | + | |
- | are exclusive (they cannot be combined) : | + | |
- | + | ||
- | * STR_REPLACE_STOP : Stop replacements (up to count(replace) occurences of needle can be replaced) | + | |
- | * STR_REPLACE_FIRST : Remaining occurences are replaced with the first element of the replace array. | + | |
- | * STR_REPLACE_LAST : Remaining occurences are replaced with the last element of the replace array. | + | |
- | * STR_REPLACE_LOOP : Loop and restart replacements with the first element of the replace array. Loop as many times as needed. | + | |
- | * STR_REPLACE_EMPTY : Remaining occurences are replaced with an empty string. | + | |
==== API changes ==== | ==== API changes ==== | ||
- | |||
- | === PHP API === | ||
- | |||
- | An additional optional argument, named //options// in the documentation, | ||
- | at the end of the argument list for str_replace() and str_ireplace(). | ||
- | |||
- | If set, its value must be one of the STR_REPLACE_xxx constants defined above. | ||
- | |||
- | When not set, the default value is STR_REPLACE_STOP. | ||
=== C API === | === C API === | ||
Line 150: | Line 102: | ||
===== Open Issues ===== | ===== Open Issues ===== | ||
- | ===== Unaffected PHP Functionality ===== | + | None |
- | The C API for php_char_to_str() and php_str_to_str() is left unchanged. | + | ===== Unaffected PHP Functionality ===== |
===== Future Scope ===== | ===== Future Scope ===== | ||
Line 168: | Line 120: | ||
===== Patches and Tests ===== | ===== Patches and Tests ===== | ||
- | Pull request against PHP7 branch : [[https:// | + | Pull request against PHP7 branch |
===== Implementation ===== | ===== Implementation ===== | ||
Line 179: | Line 132: | ||
===== References ===== | ===== References ===== | ||
- | Feature | + | Feature |
- | A similar feature request | + | * [[https:// |
+ | * [[https:// | ||
+ | * [[https:// | ||
- | PR : [[https:// | + | Pull Request |
+ | |||
+ | * [[https:// | ||
===== Rejected Features ===== | ===== Rejected Features ===== | ||
Support for arbitrarily-nested search/ | Support for arbitrarily-nested search/ | ||
+ | Additional ' | ||
- | ===== Vote ===== | ||
- | |||
- | <doodle title=" | ||
- | * Yes | ||
- | * No | ||
- | </ | ||
rfc/cyclic-replace.1422896141.txt.gz · Last modified: 2017/09/22 13:28 (external edit)