rfc:proper-range-semantics

Differences

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

Link to this comparison view

Next revision		Previous revision
Next revisionBoth sides next revision
rfc:proper-range-semantics [2023/03/22 15:22] – Created girgiasrfc:proper-range-semantics [2023/03/30 13:30] – Version 0.2 girgias
Line 1: Line 1:
 ====== PHP RFC: Define proper semantics for range() function  ====== ====== PHP RFC: Define proper semantics for range() function  ======
  
-  * Version: 0.1+  * Version: 0.2
   * Date: 2023-03-13   * Date: 2023-03-13
   * Author: George Peter Banyard, <girgias@php.net>   * Author: George Peter Banyard, <girgias@php.net>
Line 11: Line 11:
 ===== Introduction ===== ===== Introduction =====
  
-PHP's standard library implements the <php>range()</php> function, which generates an array of values going from a <php>$start</php> value to an <php>$end</php> value, by default it advances in steps of ''1'' but this behaviour can be changed by passing the <php>$step</php> parameter.+PHP's standard library implements the <php>range()</php> function, which generates an array of values going from a <php>$start</php> value to an <php>$end</php> value. 
 +By default values are generated by using a step of ''1'' but this behaviour can be changed by passing the <php>$step</php> parameter.
 In principle, the <php>range()</php> function only works with integer, float, and string <php>$start</php> and <php>$end</php> values, but in reality this is not the case. Moreover, even within those expected types the behaviour can be quite strange. In principle, the <php>range()</php> function only works with integer, float, and string <php>$start</php> and <php>$end</php> values, but in reality this is not the case. Moreover, even within those expected types the behaviour can be quite strange.
  
Line 132: Line 133:
   string(1) "E"   string(1) "E"
 } }
-</PHP> 
- 
-Example showing the ASCII code point range: 
-<PHP> 
-var_dump(range('a', 'Z')); 
-/* 
-array(8) { 
-  [0]=> 
-  string(1) "a" 
-  [1]=> 
-  string(1) "`" 
-  [2]=> 
-  string(1) "_" 
-  [3]=> 
-  string(1) "^" 
-  [4]=> 
-  string(1) "]" 
-  [5]=> 
-  string(1) "\" 
-  [6]=> 
-  string(1) "[" 
-  [7]=> 
-  string(1) "Z" 
-} 
-*/ 
 </PHP> </PHP>
  
Line 176: Line 152:
 </PHP> </PHP>
  
-Example showing how negative steps are multiplied by ''-1'':+Example showing how negative steps for increasing ranges are multiplied by ''-1'':
 <PHP> <PHP>
 var_dump(range(0, 10, -2)); var_dump(range(0, 10, -2));
Line 193: Line 169:
   int(10)   int(10)
 } }
 +</PHP>
 +
 +
 +Example showing the ASCII code point range:
 +<PHP>
 +var_dump( range("!", "/") );
 +/*
 +array(15) {
 +  [0]=>
 +  string(1) "!"
 +  [1]=>
 +  string(1) """
 +  [2]=>
 +  string(1) "#"
 +  [3]=>
 +  string(1) "$"
 +  [4]=>
 +  string(1) "%"
 +  [5]=>
 +  string(1) "&"
 +  [6]=>
 +  string(1) "'"
 +  [7]=>
 +  string(1) "("
 +  [8]=>
 +  string(1) ")"
 +  [9]=>
 +  string(1) "*"
 +  [10]=>
 +  string(1) "+"
 +  [11]=>
 +  string(1) ","
 +  [12]=>
 +  string(1) "-"
 +  [13]=>
 +  string(1) "."
 +  [14]=>
 +  string(1) "/"
 +}
 +*/
 +
 +var_dump(range('a', 'Z'));
 +/*
 +array(8) {
 +  [0]=>
 +  string(1) "a"
 +  [1]=>
 +  string(1) "`"
 +  [2]=>
 +  string(1) "_"
 +  [3]=>
 +  string(1) "^"
 +  [4]=>
 +  string(1) "]"
 +  [5]=>
 +  string(1) "\"
 +  [6]=>
 +  string(1) "["
 +  [7]=>
 +  string(1) "Z"
 +}
 +*/
 </PHP> </PHP>
  
Line 212: Line 250:
 Examples with unexpected types: Examples with unexpected types:
 <PHP> <PHP>
 +/* null */
 +var_dump(range(null, 2));
 +array(3) {
 +  [0]=>
 +  int(0)
 +  [1]=>
 +  int(1)
 +  [2]=>
 +  int(2)
 +}
 +
 +var_dump(range(null, 'e'));
 +array(1) {
 +  [0]=>
 +  int(1)
 +}
 +
 /* Array */ /* Array */
 var_dump(range([5], [8])); var_dump(range([5], [8]));
Line 297: Line 352:
   * Throw value errors if <php>$start</php>, <php>$end</php>, or <php>$step</php> is a non-finite float (-INF, INF, NAN).   * Throw value errors if <php>$start</php>, <php>$end</php>, or <php>$step</php> is a non-finite float (-INF, INF, NAN).
   * Throw a more descriptive <php>ValueError</php> when <php>$step</php> is zero.   * Throw a more descriptive <php>ValueError</php> when <php>$step</php> is zero.
-  * Emit an <php>E_WARNING</php> when passing a negative <php>$step</php> +  * Throw a <php>ValueError</php> when passing a negative <php>$step</php> for increasing ranges. 
-  * Throw a <php>ValueError</php> when <php>$start</php> or <php>$end</php> is the empty string+  * Emit an <php>E_WARNING</php> when <php>$start</php> or <php>$end</php> is the empty string, and cast the value to ''0''
   * Emit an <php>E_WARNING</php> when <php>$start</php> or <php>$end</php> has more than one byte.   * Emit an <php>E_WARNING</php> when <php>$start</php> or <php>$end</php> has more than one byte.
   * Emit an <php>E_WARNING</php> when <php>$start</php> or <php>$end</php> is cast to an integer because the other boundary input is a number or numeric string. (e.g. <php>range('5', 'z');</php> or <php>range(5, 'z');</php>)   * Emit an <php>E_WARNING</php> when <php>$start</php> or <php>$end</php> is cast to an integer because the other boundary input is a number or numeric string. (e.g. <php>range('5', 'z');</php> or <php>range(5, 'z');</php>)
Line 304: Line 359:
  
  
-Therefore, the behaviour of some of the previous would result in the following behaviour:+Therefore, the behaviour of some of the previous examples would result in the following behaviour:
  
  
 <PHP> <PHP>
-var_dump(range('', 'Z')); 
-/* 
-Warning: range(): Argument #1 ($start) must not be empty, casted to 0 in %s on line %d 
- 
-Warning: range(): Argument #1 ($start) must be a string if argument #2 ($end) is a string, argument #2 ($end) converted to 0 in %s on line %d 
-array(1) { 
-  [0]=> 
-  int(0) 
-} 
-*/ 
- 
 var_dump(range('A', 'E', 1.0)); var_dump(range('A', 'E', 1.0));
 array(5) { array(5) {
Line 332: Line 376:
   string(1) "E"   string(1) "E"
 } }
 +
 +var_dump(range('', 'Z'));
 +/*
 +Warning: range(): Argument #1 ($start) must not be empty, casted to 0
 +
 +Warning: range(): Argument #1 ($start) must be a string if argument #2 ($end) is a string, argument #2 ($end) converted to 0
 +*/
 +
 +
 +var_dump(range(null, 2));
 +/*
 +Deprecated: range(): Passing null to parameter #1 ($start) of type string|int|float is deprecated
 +array(3) {
 +  [0]=>
 +  int(0)
 +  [1]=>
 +  int(1)
 +  [2]=>
 +  int(2)
 +}
 +*/
 +
 +var_dump(range(null, 'e'));
 +/*
 +Deprecated: range(): Passing null to parameter #1 ($start) of type string|int|float is deprecated in %s on line %d
 +
 +Warning: range(): Argument #1 ($start) must be a string if argument #2 ($end) is a string, argument #2 ($end) converted to 0 in %s on line %d
 +array(1) {
 +  [0]=>
 +  int(1)
 +}
 +*/
 +
 +var_dump(range(0, 10, -2));
 +/*
 +range(): Argument #3 ($step) must be greater than 0 for increasing ranges
 +*/
 </PHP> </PHP>
  
Line 338: Line 419:
 Using Nikita Popov's [[https://github.com/nikic/popular-package-analysis|''popular-package-analysis'']] project and running a [[https://github.com/Girgias/popular-package-analysis/pull/1|rough analysis]] of the usage of <php>range()</php> on the top 1000 composer projects we get that out of around 450 calls to <php>range()</php> Using Nikita Popov's [[https://github.com/nikic/popular-package-analysis|''popular-package-analysis'']] project and running a [[https://github.com/Girgias/popular-package-analysis/pull/1|rough analysis]] of the usage of <php>range()</php> on the top 1000 composer projects we get that out of around 450 calls to <php>range()</php>
  
-  - 154 calls are made out with literal number arguments+  - 154 calls are made with literal number arguments
   - 18 calls are made with literal string arguments   - 18 calls are made with literal string arguments
   - 140 calls have at least one argument be the result of a plus (''+''), minus (''-''), or times (''*'') operation.   - 140 calls have at least one argument be the result of a plus (''+''), minus (''-''), or times (''*'') operation.
Line 346: Line 427:
      
 The calls that are non-trivial were manually checked and seem all valid. The calls that are non-trivial were manually checked and seem all valid.
- 
-Only one example, a test case in Drupal, would have triggered an <php>E_WARNING</php> about using a negative step: 
-<PHP> 
-drupal/core/modules/views/tests/src/Functional/Handler/FieldWebTest.php:102 
-Negative step is pointless 
-range(5, 1, -1) 
-</PHP> 
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 358: Line 432:
 <php>TypeError</php>s are thrown for incompatible types. <php>TypeError</php>s are thrown for incompatible types.
  
-<php>ValueError</php>s are thrown for INF, NAN, and empty string values.+<php>ValueError</php>s are thrown for INF, NAN, and negative step values for increasing ranges.
  
 <php>E_WARNING</php>s are emitted for various issues. <php>E_WARNING</php>s are emitted for various issues.
rfc/proper-range-semantics.txt · Last modified: 2023/06/19 13:41 by girgias

Page Tools