rfc:cyclic-replace

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:cyclic-replace [2015/01/09 14:41] – francoisrfc: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.0+  * Version: 1.7
   * Creation date: 2015-01-05   * Creation date: 2015-01-05
-  * Last modification date : 2015-01-09+  * Last modification date : 2015-04-02
   * Author: François Laupretre, francois@tekwire.net   * Author: François Laupretre, francois@tekwire.net
-  * Status: Under discussion+  * Status: Abandoned
   * First Published at: http://wiki.php.net/rfc/cyclic-replace   * First Published at: http://wiki.php.net/rfc/cyclic-replace
  
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, the case (string search and array replace)+In the current str_[i]replace() implementation, the case (string search / array replace)
 is supported but quite useless as, in this case, the replace array is converted to the 'Array' is supported but quite useless as, in this case, the replace array is converted to the 'Array'
 string and, then, string/string conversion is performed. string and, then, string/string conversion is performed.
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, several +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 'cyclic replace'. Purists will note that it is really 'cyclic' +
-only when we set the option to loop in the replace array but I didn't find a better name.+
  
 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 41: Line 37:
 be a string or an array. If it is a string, we have the usual string/string be a string or an array. If it is a string, we have the usual string/string
 behavior. If it is an array, cyclic replacement is performed. behavior. If it is an array, cyclic replacement is performed.
-So, the 'array search' case can be seen as an implicit loop around the+So, the 'array search' case is an implicit loop around the
 'string search' case, providing exactly the same features. 'string search' case, providing exactly the same features.
-As this is performed using recursion, search can contain any level of imbricated 
-arrays, provided replace provides the corresponding structure. 
  
-Note that, in case of multi-level arrays, replace array can be less deep than +Other feature : Arbitrarily nested subject arrays are now supported, returning exactly the same 
-search array as, as soon as we find a non-array replace value, this value is +array structure and preserving keys. Only values are replaced.
-used as replacement string for the whole corresponding search subtree. The opposite +
-case is very different : If the replace array tree is deeper than the search tree by more +
-than 1 level, array to string conversion will occur (with E_NOTICE and the +
-wonderful 'Array' result). +
- +
-Recursion also extends the behavior of 'non-cyclic' replacements as the previous +
-implementation supported only one-level arrays for search and replace arguments. +
- +
-Completely off topic but brings a cleaner design: subject arrays are now managed +
-recursively too, returning exactly the same array structure and preserving keys. Only +
-values are replaced.+
  
 Empty replace arrays are considered as unexpected. When one is provided, an Empty replace arrays are considered as unexpected. When one is provided, an
Line 66: Line 49:
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
- 
-==== C API ==== 
- 
-php_char_to_str_ex() and php_str_to_str_ex() (defined in ext/standard/php_string.h) 
-take an additional //options// 
-argument. This argument is not used at the moment but, this 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 90: Line 64:
 is raised and the subject is returned unchanged. is raised and the subject is returned unchanged.
  
-The support of multi-level arrays as search, replace, and subject brings the same+The support of arbitrarily-nested subject brings the same
 kind of BC because previous implementations supported one array level only. kind of BC because previous implementations supported one array level only.
-So, if provided with multi-level arrays, array to string conversion would have 
-been performed. 
  
 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. I think we can consider them as very low impact because+previous implementations. These can be considered as very low impact because
 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, can be considered as broken and very +functions, while theoritically supported, is very improbable.
-improbable.+
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 112: 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 122: Line 91:
 ==== New Constants ==== ==== New Constants ====
  
-=== C constants === +None
- +
-These new C constants are defined in ext/standard/php_strings.h : +
- +
- * 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. Looping occurs 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, is added 
-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 169: Line 105:
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
- 
-The C API for php_char_to_str() and php_str_to_str() is left unchanged. 
  
 ===== Future Scope ===== ===== Future Scope =====
  
-I propose the addition of similar features (cyclic replacement and multi-level +Proposed: 
-array recursion) to preg_replace() and preg_filter().+ 
 + * Add (search=null, replace=array) syntax. Would take search from array_keys(replace). An array of (search => replace) elements would be, IMO, a more intuitive way to specify multiple replacements. 
 + 
 + * Add similar features (cyclic replacement and multi-level array recursion) to preg_replace() and preg_filter().
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
  
-Required majority : probably 2/3.+Required majority : 50%+1.
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-Pull request against current PHP7 branch : [[https://github.com/php/php-src/pull/980]]+Pull request against PHP7 branch (work in progress) : [[https://github.com/php/php-src/pull/980]]
  
-When implementation will be complete, this PR is intended to be the final patch. 
  
 ===== Implementation ===== ===== Implementation =====
Line 196: Line 132:
 ===== References ===== ===== References =====
  
-Feature request : [[https://bugs.php.net/bug.php?id=38685]]+Feature Requests :
  
-A similar feature request : [[https://bugs.php.net/bug.php?id=62315]]+  * [[https://bugs.php.net/bug.php?id=38685]] 
 +  * [[https://bugs.php.net/bug.php?id=62315]] 
 +  * [[https://bugs.php.net/bug.php?id=14523]]
  
-PR : [[https://github.com/php/php-src/pull/980]]+Pull Request : 
 + 
 +  * [[https://github.com/php/php-src/pull/980]]
  
 ===== Rejected Features ===== ===== Rejected Features =====
  
-(Keep this updated with features that were discussed on the mail lists)+Support for arbitrarily-nested search/replace arrays is abandoned. 
 +Additional 'options' argument to str_replace() is abandoned. 
  
rfc/cyclic-replace.1420814467.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools