Skip to content

range: Update for PHP 8.3 #2801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TimWolla merged 7 commits into from
Oct 16, 2023
Merged

range: Update for PHP 8.3 #2801

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ede1cf3
Update range() documentation for PHP 8.3 changes
Girgias Sep 27, 2023
f9bd91d
Remove default val
Girgias Oct 6, 2023
9568b80
Address review
Girgias Oct 6, 2023
2b32e0f
Improve end inclusion wording
Girgias Oct 7, 2023
1d1ed7a
review comments
Girgias Oct 7, 2023
40053bb
Review
Girgias Oct 9, 2023
69fb772
Fix typos
TimWolla Oct 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 203 additions & 41 deletions reference/array/functions/range.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.range" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>range</refname>
Expand All @@ -16,7 +15,19 @@
<para>
Create an array containing a range of elements.
</para>
<para>
If both <parameter>start</parameter> and <parameter>end</parameter> are
<type>string</type>s, and <parameter>step</parameter> is <type>int</type>
the produced array will be a sequence of bytes.
Otherwise, the produced array will be a sequence of numbers.
</para>
<para>
The sequence is increasing if <parameter>start</parameter> is less than
equal to <parameter>end</parameter>.
Otherwise, the sequence is decreasing.
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
Expand All @@ -33,32 +44,198 @@
<term><parameter>end</parameter></term>
<listitem>
<para>
The sequence is ended upon reaching the
<parameter>end</parameter> value.
Last possible value of the sequence.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>step</parameter></term>
<listitem>
<para>
If a <parameter>step</parameter> value is given, it will be used as the
increment (or decrement) between elements in the sequence. <parameter>step</parameter>
must not equal <literal>0</literal> and must not exceed the specified range. If not specified,
<parameter>step</parameter> will default to 1.
<parameter>step</parameter> indicates by how much is the produced
sequence progressed between values of the sequence.
</para>
<para>
<parameter>step</parameter> may be negative for decreasing sequences.
</para>
<para>
If <parameter>step</parameter> is a <type>float</type> without a
fractional part, it is interpreted as <type>int</type>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of elements from <parameter>start</parameter> to
<parameter>end</parameter>, inclusive.
Returns a sequence of elements as an <type>array</type> with the first
element being <parameter>start</parameter> going up to
<parameter>end</parameter>, with each value of the sequence being
<parameter>step</parameter> values apart.
</para>
<para>
The last element of the returned array is either <parameter>end</parameter>
or the previous element of the sequence,
depending on the value of <parameter>step</parameter>.
</para>
<para>
If both <parameter>start</parameter> and <parameter>end</parameter> are
<type>string</type>s, and <parameter>step</parameter> is <type>int</type>
the produced array will be a sequence of bytes,
generally latin <abbrev>ASCII</abbrev> characters.
</para>
<para>
If at least one of <parameter>start</parameter>, <parameter>end</parameter>,
or <parameter>step</parameter> is <type>float</type>
the produced array will be a sequence of <type>float</type>.
</para>
<para>
Otherwise, the produced array will be a sequence of <type>int</type>.
</para>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<itemizedlist>
<listitem>
<simpara>
If <parameter>step</parameter> is <literal>0</literal>,
a <classname>ValueError</classname> is thrown.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>start</parameter>, <parameter>end</parameter>,
or <parameter>step</parameter> is not <function>is_finite</function>,
a <classname>ValueError</classname> is thrown.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>step</parameter> is negative,
but the produced range is increasing
(i.e. <code>$start &lt;= $end</code>),
a <classname>ValueError</classname> is thrown.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>start</parameter> or <parameter>end</parameter>
is the empty string <literal>''</literal>,
an <constant>E_WARNING</constant> is emitted and
the empty string will be interpreted as <literal>0</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>start</parameter> or <parameter>end</parameter>
non-<link linkend="language.types.numeric-strings">numeric string</link>
with more than one byte, an <constant>E_WARNING</constant> is emitted.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>start</parameter> or <parameter>end</parameter> is a string
that is implicitly cast to an <type>int</type> because the other boundary
value is a number, an <constant>E_WARNING</constant> is emitted.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>step</parameter> is a <type>float</type>,
and <parameter>start</parameter> and <parameter>end</parameter> are
non-<link linkend="language.types.numeric-strings">numeric string</link>,
an <constant>E_WARNING</constant> is emitted.
</simpara>
</listitem>
</itemizedlist>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.3.0</entry>
<entry>
If both <parameter>start</parameter> and <parameter>end</parameter>
are strings then <function>range</function> will now always produce
an <type>array</type> of bytes.
Previously if one of the boundary values was a numeric string,
then the other boundary value was implicitly cast to <type>int</type>.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
An <constant>E_WARNING</constant> is now emitted if
<parameter>start</parameter> or <parameter>end</parameter>
is a string that is implicitly cast to <type>int</type>
because the other boundary value is a number.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
An <constant>E_WARNING</constant> is now emitted if
<parameter>start</parameter> or <parameter>end</parameter>
is a non-numeric string with more than one byte.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
An <constant>E_WARNING</constant> is now emitted if
<parameter>start</parameter> or <parameter>end</parameter>
is the empty string.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
If <parameter>step</parameter> is a <type>float</type> with no
fractional part, it will be interpreted as an <type>int</type>.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
A <classname>ValueError</classname> is now thrown if
<parameter>step</parameter> is negative when producing an increasing
range.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
A <classname>ValueError</classname> is now thrown if
<parameter>step</parameter> is not finite.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
A <classname>TypeError</classname> is now thrown if
<parameter>start</parameter> or <parameter>end</parameter>
is an <type>array</type>, <type>object</type>, or <type>resource</type>.
Previously they were implicitly cast to <type>int</type>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
Expand All @@ -67,48 +244,32 @@
<programlisting role="php">
<![CDATA[
<?php
// array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
foreach (range(0, 12) as $number) {
echo $number;
}
echo implode(', ', range(0, 12)), PHP_EOL;

echo "\n";
echo implode(', ', range(0, 100, 10)), PHP_EOL;

// The step parameter
// array(0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
foreach (range(0, 100, 10) as $number) {
echo $number;
}
echo implode(', ', range('a', 'i')), PHP_EOL;

echo "\n";
echo implode(', ', range('c', 'a')), PHP_EOL;

// Usage of character sequences
// array('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i');
foreach (range('a', 'i') as $letter) {
echo $letter;
}

echo "\n";

// array('c', 'b', 'a');
foreach (range('c', 'a') as $letter) {
echo $letter;
}
echo implode(', ', range('A', 'z')), PHP_EOL;
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100
a, b, c, d, e, f, g, h, i
c, b, a
A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, [, \, ], ^, _, `, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Character sequence values are limited to a length of one. If a length greater
than one is entered, only the first character is used.
</para>
</note>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
Expand All @@ -119,6 +280,7 @@ foreach (range('c', 'a') as $letter) {
</simplelist>
</para>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
Expand Down