[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] [doc-en] master: Add docs about array destructuring (#796)
From:       Kamil Tekiela via GitHub <noreply () php ! net>
Date:       2022-08-18 11:29:47
Message-ID: P2PVztxp3DrWH5MJVXfmTXWJUrdk4JY0G7eqv0yzKw () main ! php ! net
[Download RAW message or body]

Author: Kamil Tekiela (kamil-tekiela)
Committer: GitHub (web-flow)
Pusher: kamil-tekiela
Date: 2022-08-18T12:21:58+01:00

Commit: https://github.com/php/doc-en/commit/fb6ffde9728aa008bf89e9d0043de8d8acc2bb82
Raw diff: https://github.com/php/doc-en/commit/fb6ffde9728aa008bf89e9d0043de8d8acc2bb82.diff

Add docs about array destructuring (#796)

Changed paths:
  M  language/types/array.xml


Diff:

diff --git a/language/types/array.xml b/language/types/array.xml
index 7235819b78e..04f4eaa16c3 100644
--- a/language/types/array.xml
+++ b/language/types/array.xml
@@ -375,9 +375,6 @@ function getArray() {
 }
 
 $secondElement = getArray()[1];
-
-// or
-list(, $secondElement) = getArray();
 ?>
 ]]>
     </programlisting>
@@ -535,11 +532,144 @@ Array
 )
 ]]>
      </screen>
-    </informalexample>       
+    </informalexample>
+
+   </note>
+
+  </sect3>
+
+  <sect3 xml:id="language.types.array.syntax.destructuring">
+   <title>Array destructuring</title>
+
+   <para>
+    Arrays can be destructured using the <literal>[]</literal> (as of PHP 7.1.0) or
+    <function>list</function> language constructs. These
+    constructs can be used to destructure an array into distinct variables.
+   </para>
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$source_array = ['foo', 'bar', 'baz'];
+
+[$foo, $bar, $baz] = $source_array;
+
+echo $foo;    // prints "foo"
+echo $bar;    // prints "bar"
+echo $baz;    // prints "baz"
+?>
+]]>
+    </programlisting>
+   </informalexample>
+
+   <para>
+    Array destructuring can be used in &foreach; to destructure
+    a multi-dimensional array while iterating over it.
+   </para>
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$source_array = [
+    [1, 'John'],
+    [2, 'Jane'],
+];
+
+foreach ($source_array as [$id, $name]) {
+    // logic here with $id and $name
+}
+?>
+]]>
+    </programlisting>
+   </informalexample>
+
+   <para>
+    Array elements will be ignored if the variable is not provided. Array
+    destructuring always starts at index <literal>0</literal>.
+   </para>
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$source_array = ['foo', 'bar', 'baz'];
+
+// Assign the element at index 2 to the variable $baz
+[, , $baz] = $source_array;
+
+echo $baz;    // prints "baz"
+?>
+]]>
+    </programlisting>
+   </informalexample>
+
+   <para>
+    As of PHP 7.1.0, associative arrays can be destructured too. This also
+    allows for easier selection of the right element in numerically indexed
+    arrays as the index can be explicitly specified.
+   </para>
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];
+
+// Assign the element at index 'baz' to the variable $three
+['baz' => $three] = $source_array;
+
+echo $three;    // prints 3
+
+$source_array = ['foo', 'bar', 'baz'];
+
+// Assign the element at index 2 to the variable $baz
+[2 => $baz] = $source_array;
+
+echo $baz;    // prints "baz"
+?>
+]]>
+    </programlisting>
+   </informalexample>
+
+   <para>
+    Array destructuring can be used for easy swapping of two variables.
+   </para>
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$a = 1;
+$b = 2;
+
+[$b, $a] = [$a, $b];
+
+echo $a;    // prints 2
+echo $b;    // prints 1
+?>
+]]>
+    </programlisting>
+   </informalexample>
 
+   <note>
+    <para>
+      The spread operator (<literal>...</literal>) is not supported in assignments.
+    </para>
    </note>
 
+   <note>
+    <para>
+      Attempting to access an array key which has not been defined is
+      the same as accessing any other undefined variable:
+      an <constant>E_NOTICE</constant>-level error message
+      (<constant>E_WARNING</constant>-level as of PHP 8.0.0) will be
+      issued, and the result will be &null;.
+    </para>
+   </note>
   </sect3>
+
  </sect2><!-- end syntax -->
  
  <sect2 xml:id="language.types.array.useful-funcs">

-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]