rfc:proper-range-semantics

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:proper-range-semantics [2023/03/30 13:30] – Version 0.2 girgiasrfc:proper-range-semantics [2023/06/19 13:41] (current) – Implemented girgias
Line 1: Line 1:
 ====== PHP RFC: Define proper semantics for range() function  ====== ====== PHP RFC: Define proper semantics for range() function  ======
  
-  * Version: 0.2+  * Version: 0.3
   * Date: 2023-03-13   * Date: 2023-03-13
   * Author: George Peter Banyard, <girgias@php.net>   * Author: George Peter Banyard, <girgias@php.net>
-  * Status: Under Discussion+  * Status: Implemented (https://github.com/php/php-src/commit/798c40a739e8f1081a516679a367d76c3d0aabb9)
   * Target Version: PHP 8.3   * Target Version: PHP 8.3
   * Implementation: [[https://github.com/php/php-src/pull/10826]]   * Implementation: [[https://github.com/php/php-src/pull/10826]]
Line 19: Line 19:
 The current behaviour is quite complex, and it might be easier to just read the implementation, but it roughly goes as follows: The current behaviour is quite complex, and it might be easier to just read the implementation, but it roughly goes as follows:
  
-First, check if the <php>$step</php> argument is negative, if it is multiply by ''-1''.+First, check if the <php>$step</php> argument is negative; if it is multiply by ''-1''.
  
 Then check the boundary arguments: Then check the boundary arguments:
  
   * If both start and end values are strings with at least one byte (e.g. <php>range('A', 'Z');</php>, <php>range('AA', 'BB');</php>, or <php>range('15', '25');</php>):   * If both start and end values are strings with at least one byte (e.g. <php>range('A', 'Z');</php>, <php>range('AA', 'BB');</php>, or <php>range('15', '25');</php>):
-    * If one of the inputs is a float numeric string, or the <php>$step</php> parameter is a float: go to the handle float input branch +    * If one of the inputs is a float numeric string, or the <php>$step</php> parameter is a float: go to the handle float input branch. 
-    * If one of the inputs is an integer numeric string: go to the generic handling branch+    * If one of the inputs is an integer numeric string: go to the generic handling branch.
     * Otherwise: discard every byte after the first one and return an array of ASCII characters going from the start ASCII code point to the end ASCII code point.     * Otherwise: discard every byte after the first one and return an array of ASCII characters going from the start ASCII code point to the end ASCII code point.
-  * If one of the start or end value is a float or the <php>$step</php> parameter is a float  (e.g. <php>range(10.5, 12);</php>, <php>range(1, 3, 1.5);</php>, or <php>range(1, 3, 1.0);</php>): cast start and end values to float and return an array of floats +  * If the start or end value is a float or the <php>$step</php> parameter is a float  (e.g. <php>range(10.5, 12);</php>, <php>range(1, 3, 1.5);</php>, or <php>range(1, 3, 1.0);</php>): cast start and end values to float and return an array of floats. 
-  * Otherwise (generic handling): cast start and end values to int and return an array of int.+  * Otherwise (generic handling): cast start and end values to int and return an array of integers.
      
 The generic case will accept //any// type. The generic case will accept //any// type.
Line 132: Line 132:
   [4]   [4]
   string(1) "E"   string(1) "E"
 +}
 +
 +
 +var_dump(range('1', '3'));
 +array(3) {
 +  [0]=>
 +  int(1)
 +  [1]=>
 +  int(2)
 +  [2]=>
 +  int(3)
 } }
 </PHP> </PHP>
Line 322: Line 333:
 ==== Issues surrounding usage of INF and NAN values ==== ==== Issues surrounding usage of INF and NAN values ====
  
-Infinite values are handles as part of the range boundary checks, or for the <php>$step</php> parameter when checking that the step is less than the range being requested, and will throw ValueErrors.+Infinite values are handled as part of the range boundary checks, or for the <php>$step</php> parameter when checking that the step is less than the range being requested, and will throw ValueErrors.
  
 However, NAN values are not specifically handled and result in nonsensical ranges: However, NAN values are not specifically handled and result in nonsensical ranges:
Line 339: Line 350:
 </PHP> </PHP>
  
-Where using a NAN values as a step even breaks the expectation that <php>range()</php> will return a non empty list.+Where using a NAN value as a step even breaks the expectation that <php>range()</php> will return a non empty list.
  
 +==== Issues surrounding usage of string digits ====
 +
 +If one of the boundary inputs is a string digit (e.g. ''"1"'') both inputs will be interpreted as numbers.
 +This doesn't pose too much of an issue if both inputs are string digits as it will generate a list of integers.
 +
 +However, if the other input is a non-numeric string the expected behaviour of generating a list of ASCII characters is not upheld anymore:
 +<PHP>
 +var_dump( range("9", "A") );
 +array(10) {
 +  [0]=>
 +  int(9)
 +  [1]=>
 +  int(8)
 +  [2]=>
 +  int(7)
 +  [3]=>
 +  int(6)
 +  [4]=>
 +  int(5)
 +  [5]=>
 +  int(4)
 +  [6]=>
 +  int(3)
 +  [7]=>
 +  int(2)
 +  [8]=>
 +  int(1)
 +  [9]=>
 +  int(0)
 +}
 +</PHP>
 +instead of the expected:
 +<PHP>
 +var_dump( range("9", "A") );
 +array(9) {
 +  [0]=>
 +  string(1) "9"
 +  [1]=>
 +  string(1) ":"
 +  [2]=>
 +  string(1) ";"
 +  [3]=>
 +  string(1) "<"
 +  [4]=>
 +  string(1) "="
 +  [5]=>
 +  string(1) ">"
 +  [6]=>
 +  string(1) "?"
 +  [7]=>
 +  string(1) "@"
 +  [8]=>
 +  string(1) "A"
 +}
 +</PHP>
  
 ===== Proposal ===== ===== Proposal =====
Line 348: Line 414:
 The changes are as follows: The changes are as follows:
  
-  * If <php>$step</php> is a float but is compatible with ''int'' interpret it as an integer. +  * If <php>$step</php> is a float but is compatible with ''int'' (i.e. <php>(float)(int)$step === $step</php>) interpret it as an integer. 
-  * Introduce and use a proper ZPP check for ''int|float|string'' <php>$start</php> and <php>$end</php> parameters, this will cause <php>TypeError</php>s to be thrown when passing objects, resources, and arrays to <php>range()</php>. It will also cause a deprecation warning to be emitted when passing ''null''.+  * Introduce and use a proper ZPP check for ''int|float|string'' <php>$start</php> and <php>$end</php> parameters; this will cause <php>TypeError</php>s to be thrown when passing objects, resources, and arrays to <php>range()</php>. It will also cause a deprecation warning to be emitted when passing ''null''.
   * 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.
   * Throw a <php>ValueError</php> when passing a negative <php>$step</php> for increasing ranges.   * Throw a <php>ValueError</php> when passing a negative <php>$step</php> for increasing ranges.
   * 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> 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 if it is a non-numeric string. 
-  * 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. (e.g. <php>range(5, 'z');</php>) 
-  * Emit an <php>E_WARNING</php> when <php>$step</php> is a float when trying to generate a range of characters.+  * Produce a list of characters if one of the boundary inputs is a string digit instead of casting the other input to int (e.g. <php>range('5', 'z');</php>) 
 +  * Emit an <php>E_WARNING</php> when <php>$step</php> is a float when trying to generate a range of characters, except if both boundary inputs are numeric strings (e.g. <php>range('5', '9', 0.5);</php> does not produce a warning).
  
  
Line 375: Line 442:
   [4]=>   [4]=>
   string(1) "E"   string(1) "E"
 +}
 +
 +var_dump( range("9", "A") );
 +array(9) {
 +  [0]=>
 +  string(1) "9"
 +  [1]=>
 +  string(1) ":"
 +  [2]=>
 +  string(1) ";"
 +  [3]=>
 +  string(1) "<"
 +  [4]=>
 +  string(1) "="
 +  [5]=>
 +  string(1) ">"
 +  [6]=>
 +  string(1) "?"
 +  [7]=>
 +  string(1) "@"
 +  [8]=>
 +  string(1) "A"
 } }
  
Line 436: Line 525:
 <php>E_WARNING</php>s are emitted for various issues. <php>E_WARNING</php>s are emitted for various issues.
  
-Calls to <php>range()</php> that have integer boundaries but a float step that is compatible as an integer will now return an array of integers instead of an array of float:+Calls to <php>range()</php> that have integer boundaries but a float step that is compatible as an integer will now return an array of integers instead of an array of floats:
 <PHP> <PHP>
 var_dump( range(1, 5, 2.0) ); var_dump( range(1, 5, 2.0) );
Line 467: Line 556:
 As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted. As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.
  
-Voting started on 2023-XX-XX and will end on 2023-XX-XX.+Voting started on 2023-06-01 and will end on 2023-06-15.
 <doodle title="Accept Saner range() semantics RFC?" auth="girgias" voteType="single" closed="true"> <doodle title="Accept Saner range() semantics RFC?" auth="girgias" voteType="single" closed="true">
    * Yes    * Yes
Line 477: Line 566:
 GitHub pull request: https://github.com/php/php-src/pull/10826 GitHub pull request: https://github.com/php/php-src/pull/10826
  
-After the project is implemented, this section should contain +Implemented in PHP 8.3, as commit: https://github.com/php/php-src/commit/798c40a739e8f1081a516679a367d76c3d0aabb9
- +
-  * the version(s) it was merged into +
-  * a link to the git commit(s) +
-  * a link to the PHP manual entry for the feature+
  
 ===== References ===== ===== References =====
  
rfc/proper-range-semantics.1680183042.txt.gz · Last modified: 2023/03/30 13:30 by girgias

Page Tools