svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml language/operators.xml
| From: | Adam Harvey | Date: | Sun, 09 Aug 2015 01:16:37 +0000 |
| Subject: | svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml language/operators.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-13544@lists.php.net to get a copy of this message | ||
aharvey Sun, 09 Aug 2015 01:16:37 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=337361
Log:
Update new operator documentation.
This includes removing some of the examples from the migration guide: that
needs to be punchy. We can reinsert them later in the operators reference if
they're of use.
Changed paths:
U phpdoc/en/trunk/appendices/migration70/new-features.xml
U phpdoc/en/trunk/language/operators.xml
Modified: phpdoc/en/trunk/appendices/migration70/new-features.xml
===================================================================
--- phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-08-09 01:16:32 UTC (rev 337360)
+++ phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-08-09 01:16:37 UTC (rev 337361)
@@ -5,69 +5,51 @@
<title>New features</title>
<sect2 xml:id="migration70.new-features.null-coalesce-op">
- <title>Null Coalesce Operator</title>
+ <title>Null coalesce operator</title>
<para>
- New operator has been added, which returns the result of its first operand
- if it exists and is not &null;, or else returns its second operand. This
- operator is similiar to the regular ternary operator (<literal>?</literal>),
- but it is safe to use with variables that can be &null;
+ The null coalesce operator (<literal>??</literal>) has been added as
+ syntactic sugar for the common case of needing to use a ternary in
+ conjunction with <function>isset</function>. It returns its first operand
+ if it exists and is not &null;; otherwise it returns its second operand.
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
-// Fetches the value of $_GET['user'] and returns 'nobody' if it does not
exist.
+// Fetches the value of $_GET['user'] and returns 'nobody'
+// if it does not exist.
$username = $_GET['user'] ?? 'nobody';
-// ...it means that it is equivalent to:
+// This is equivalent to:
$username = isset($_GET['user']) ? $_GET['user'] : 'nobody';
-
-// Hypothetical function fetching page from the database. If function fails, some
-// default page is returned.
-$page = Page::get($id) ?? $default_page;
-// equivalent to:
-if (($page = Page::get($id)) === NULL) {
- $page = $default_page;
-}
-// or written even more verbosely:
-if (Page::get($id) !== NULL) {
- $page = Page::get($id);
-}
-else {
- $page = $default_page;
-}
-
-// Parses image metadata, and if the width is missing, assumes 100
-$image = get_image_metadata(); // just a hypothetical function
-
-$width = $image['width'] ?? 100;
-// which is an equivalent to:
-$width = isset($image['width']) ? $image['width'] : 100;
-
+// Coalesces can be chained: this will return the first
+// defined value out of $_GET['user'], $_POST['user'], and
+// 'nobody'.
+$username = $_GET['user'] ?? $_POST['user'] ?? 'nobody';
?>
]]>
</programlisting>
</informalexample>
-
- <!-- TODO: describe chaining and precedence -->
-
+
+ <!-- TODO: we don't need further details here, but this still has to be
+ added to the operator precedence table -->
</sect2>
<sect2 xml:id="migration70.new-features.spaceship-op">
- <title>Spaceship Operator</title>
+ <title>Spaceship operator</title>
<para>
- An <type>integer</type> less than, equal to, or greater than zero when
- <varname>$a</varname> is respectively less than, equal to, or greater
- than <varname>$b</varname>.Available as of PHP 7.
+ The spaceship operator is used for comparing two expressions. It returns an
+ <type>integer</type> less than, equal to, or greater than zero when
+ <varname>$a</varname> is respectively less than, equal to, or greater than
+ <varname>$b</varname>. Comparisons are performed according to PHP's usual
+ <link linkend="types.comparisons">type comparison rules</link>.
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
-<?php
-
// Integers
echo 1 <=> 1; // 0
echo 1 <=> 2; // -1
@@ -82,20 +64,15 @@
echo "a" <=> "a"; // 0
echo "a" <=> "b"; // -1
echo "b" <=> "a"; // 1
-
-echo "a" <=> "aa"; // -1
-echo "zz" <=> "aa"; // 1
-
-// Arrays
-echo [] <=> []; // 0
-echo [1, 2, 3] <=> [1, 2, 3]; // 0
-echo [1, 2, 3] <=> []; // 3
-echo [1, 2, 3] <=> [1, 2, 1]; // 1
-echo [1, 2, 3] <=> [1, 2, 4]; // -1
+?>
]]>
</programlisting>
</informalexample>
+
+ <!-- TODO: we don't need further details here, but this still has to be
+ added to the operator precedence table -->
</sect2>
+
<sect2 xml:id="migration70.new-features.define-array">
<title>Constant arrays using <function>define</function></title>
Modified: phpdoc/en/trunk/language/operators.xml
===================================================================
--- phpdoc/en/trunk/language/operators.xml 2015-08-09 01:16:32 UTC (rev 337360)
+++ phpdoc/en/trunk/language/operators.xml 2015-08-09 01:16:37 UTC (rev 337361)
@@ -1283,20 +1283,19 @@
</row>
<row>
<entry>$a <=> $b</entry>
- <entry>Spaceship Operator</entry>
+ <entry>Spaceship</entry>
<entry>
An <type>integer</type> less than, equal to, or greater than zero when
<varname>$a</varname> is respectively less than, equal to, or greater
- than <varname>$b</varname>.
- Available as of PHP 7.
+ than <varname>$b</varname>. Available as of PHP 7.
</entry>
</row>
<row>
<entry>$a ?? $b ?? $c</entry>
- <entry>Null Coalesce Operator</entry>
+ <entry>Null coalesce</entry>
<entry>
- Returns the first operand from left to right that exists and not &null;.
- If nothing exists will return &null;. Available as of PHP 7.
+ The first operand from left to right that exists and is not &null;.
+ &null; if no values are defined and not &null;. Available as of PHP 7.
</entry>
</row>
</tbody>