PHP: rfc:proper-range-semantics

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Define proper semantics for range() function  ======

  * Version: 0.3
  * Date: 2023-03-13
  * Author: George Peter Banyard, <girgias@php.net>
  * Status: Implemented (https://github.com/php/php-src/commit/798c40a739e8f1081a516679a367d76c3d0aabb9)
  * Target Version: PHP 8.3
  * Implementation: [[https://github.com/php/php-src/pull/10826]]
  * First Published at: [[http://wiki.php.net/rfc/proper-range-semantics]]

===== 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 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.

==== Current Behaviour of range() ===

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''.

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 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.
    * 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 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 integers.
  
The generic case will accept //any// type.

Let us look at various examples to highlight the range of behaviour exhibited by <php>range()</php>


=== Examples ===

Example with expected values:
<PHP>
var_dump(range(1, 3));
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

var_dump(range(1.0, 3.0));
array(3) {
  [0]
  float(1)
  [1]
  float(2)
  [2]
  float(3)
}

var_dump(range(1, 3, 1.5));
array(2) {
  [0]
  float(1)
  [1]
  float(2.5)
}


var_dump(range(1.0, 3.0, 1.5));
array(2) {
  [0]
  float(1)
  [1]
  float(2.5)
}

var_dump(range('10', '13'));
array(4) {
  [0]
  int(10)
  [1]
  int(11)
  [2]
  int(12)
  [3]
  int(13)
}

var_dump(range('10.0', '13.0'));
array(4) {
  [0]
  float(10)
  [1]
  float(11)
  [2]
  float(12)
  [3]
  float(13)
}

var_dump(range('10', '13', 1.5));
array(3) {
  [0]
  float(10)
  [1]
  float(11.5)
  [2]
  float(13)
}

var_dump(range('10.0', '13.0', 1.5));
array(3) {
  [0]
  float(10)
  [1]
  float(11.5)
  [2]
  float(13)
}

var_dump(range('A', 'E'));
array(5) {
  [0]
  string(1) "A"
  [1]
  string(1) "B"
  [2]
  string(1) "C"
  [3]
  string(1) "D"
  [4]
  string(1) "E"
}


var_dump(range('1', '3'));
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}
</PHP>

Example showing how to produce a decreasing range:
<PHP>
var_dump(range('E', 'A'));
array(5) {
  [0]
  string(1) "E"
  [1]
  string(1) "D"
  [2]
  string(1) "C"
  [3]
  string(1) "B"
  [4]
  string(1) "A"
}
</PHP>

Example showing how negative steps for increasing ranges are multiplied by ''-1'':
<PHP>
var_dump(range(0, 10, -2));
array(6) {
  [0]=>
  int(0)
  [1]=>
  int(2)
  [2]=>
  int(4)
  [3]=>
  int(6)
  [4]=>
  int(8)
  [5]=>
  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>

Example showing how string inputs can get cast to int/float:
<PHP>
var_dump(range('', 'Z'));
array(1) {
  [0]=>
  int(0)
}

var_dump(range('A', 'E', 1.0));
array(1) {
  [0]=>
  float(0)
}
</PHP>

Examples with unexpected types:
<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 */
var_dump(range([5], [8]));
array(1) {
  [0]=>
  int(1)
}

/* Resources */
var_dump(range(STDIN, STDERR));
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

/* Int/Float castable object */
$o1 = gmp_init(15);
$o2 = gmp_init(20);
var_dump(range($o1, $o2));
array(6) {
  [0]=>
  int(15)
  [1]=>
  int(16)
  [2]=>
  int(17)
  [3]=>
  int(18)
  [4]=>
  int(19)
  [5]=>
  int(20)
}

/* Int/Float non-castable object */
$o1 = new stdClass();
$o2 = new stdClass();
var_dump(range($o1, $o2));
/*

Warning: Object of class stdClass could not be converted to int in /tmp/preview on line 13

Warning: Object of class stdClass could not be converted to int in /tmp/preview on line 13
array(1) {
  [0]=>
  int(1)
}
*/
</PHP>

==== Issues surrounding usage of INF and NAN values ====

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:
<PHP>
$nan = fdiv(0,0);

var_dump(range($nan, 5));
array(1) {
  [0]=>
  float(NAN)
}

var_dump(range(1, 5, $nan));
array(0) {
}
</PHP>

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 =====

The proposal is to adjust the semantics of <php>range()</php> in various ways to throw exceptions outright or at least warn when passing unusable arguments to <php>range()</php>.

The changes are as follows:

  * 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''.
  * 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 <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> 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. (e.g. <php>range(5, 'z');</php>)
  * 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).


Therefore, the behaviour of some of the previous examples would result in the following behaviour:


<PHP>
var_dump(range('A', 'E', 1.0));
array(5) {
  [0]=>
  string(1) "A"
  [1]=>
  string(1) "B"
  [2]=>
  string(1) "C"
  [3]=>
  string(1) "D"
  [4]=>
  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"
}

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>

===== Impact Analysis =====

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 with literal number 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.
  - 47 calls have at least one argument be a variable
  - 25 calls have an argument made from a function that returns a number (<php>count()</php>, <php>min()</php>, or <php>max()</php>)
  - 66 calls have at least an argument that comes from a class property, class method, function, or array dimension.
  
The calls that are non-trivial were manually checked and seem all valid.

===== Backward Incompatible Changes =====

<php>TypeError</php>s are thrown for incompatible types.

<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.

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>
var_dump( range(1, 5, 2.0) );
/* New Behaviour */
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(3)
  [2]=>
  int(5)
}
/* Current Behaviour */
array(3) {
  [0]=>
  float(1)
  [1]=>
  float(3)
  [2]=>
  float(5)
}
</PHP>

===== Proposed PHP Version =====

Next minor version, i.e. PHP 8.3.0.

===== Proposed Voting Choices =====

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-06-01 and will end on 2023-06-15.
<doodle title="Accept Saner range() semantics RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Implementation =====

GitHub pull request: https://github.com/php/php-src/pull/10826

Implemented in PHP 8.3, as commit: https://github.com/php/php-src/commit/798c40a739e8f1081a516679a367d76c3d0aabb9

===== References =====
Page Tools
