svn: /phpdoc/bg/trunk/language/control-structures/ foreach.xml

Modified: phpdoc/bg/trunk/language/control-structures/foreach.xml
===================================================================
--- phpdoc/bg/trunk/language/control-structures/foreach.xml	2015-12-12 17:19:35 UTC (rev 338245)
+++ phpdoc/bg/trunk/language/control-structures/foreach.xml	2015-12-12 17:21:46 UTC (rev 338246)
@@ -1,70 +1,66 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: n/a Maintainer: kouber Status: ready -->
+<!-- EN-Revision: 337339 Maintainer: stanprog Status: in_progress -->
+<!-- Reviewed: yes Maintainer: stanprog -->
+<!-- CREDITS: kouber -->

 <sect1 xml:id="control-structures.foreach" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title><literal>foreach</literal></title>
+ <?phpdoc print-version-for="foreach"?>
  <para>
-  В PHP 4 беше въведена конструкция <literal>foreach</literal> (за всеки),
-  много наподобяваща тази в Perl и в някои други езици. Тя предоставя лесен
-  начин за обхождане на масиви. <literal>foreach</literal> работи само с масиви и
-  ще изведе грешка, ако се опитате да я използвате върху променлива от друг
-  тип или върху неинициализирана променлива. Съществуват два синтаксиса;
-  вторият е минимално, но полезно разширение на първия:
+  Конструкцията <literal>foreach</literal> предоставя лесен
+  начин за обхождане на масиви. <literal>foreach</literal> работи само с масиви
+  и обекти, и ще изведе грешка, ако се опитате да я използвате върху променлива
+  от друг тип или върху неинициализирана променлива. Съществуват два
+  синтаксиса:
   <informalexample>
    <programlisting>
 <![CDATA[
 foreach (array_expression as $value)
-statement
+    израз
 foreach (array_expression as $key => $value)
-statement
+    израз
 ]]>
    </programlisting>
   </informalexample>
  </para>
  <simpara>
   Първата форма обикаля през зададения от <literal>array_expression</literal>
-  масив. При всяка итерация стойността на текущия елемент се присвоява
-  на <literal>$value</literal> и вътрешният указател на масива се придвижва
-  с единица (така че при следващата итерация,
+  масив. При всяка итерация стойността на
+  текущия елемент се присвоява на <literal>$value</literal> и
+  вътрешният указател на масива се увеличава с единица (така че при следващата итерация,
   ще гледате следващия елемент).
  </simpara>
  <simpara>
-  Втората форма прави същото нещо, с тази разлика, че ключът на
-  текущия елемент ще бъде присвоен
-  на променливата <literal>$key</literal> при всяка итерация.
+  Втората форма прави същото нещо, с тази разлика, че ключът на текущия елемент ще
+  бъде присвоен на променливата <literal>$key</literal> при всяка итерация.
  </simpara>
  <simpara>
-  След PHP 5 е възможно също да
+  Възможно също да
   <link linkend="language.oop5.iterations">обхождате и обекти</link>.
  </simpara>
  <para>
   <note>
    <para>
-    Когато <literal>foreach</literal> започва първоначалното си изпълнение,
-    вътрешният указател на масива автоматично се нулира, така че да сочи към
-    първия елемент на масива. Това означава, че няма нужда да извиквате
-    <function>reset</function> преди цикъл <literal>foreach</literal>.
+    В PHP5, когато <literal>foreach</literal> започва първоначалното си изпълнение,
+    вътрешният указател на масива автоматично се нулира, така че да сочи към първия елемент на
+    масива. Това означава, че няма нужда да извиквате<function>reset</function>
+    преди цикъл <literal>foreach</literal>.
    </para>
-  </note>
- </para>
- <para>
-  <note>
    <para>
-    С изключение на случаите, в които масивът е
-    <link linkend="language.references">указан с референция</link>,
-    <literal>foreach</literal> ще работи с копие от зададения масив,
-    а не със самия масив. <literal>foreach</literal> има някои странични ефекти
-    върху указателя на масива. Не разчитайте на указателя на масива по време
-    или след изпълнението на foreach без да сте го изчистили изрично.
+    Тъй като <literal>foreach</literal> разчита на вътрешния указател на мазива в PHP
+    5, промяната му в тялото на масиви може да доведе до неучаквани резултати.
    </para>
+   <para>
+    В PHP 7, <literal>foreach</literal> не използва вътрешен указател
+    на масива.
+   </para>
   </note>
  </para>
  <para>
-  От PHP 5 нататък лесно можете да променяте елементите на даден масив като предшествате
-  <literal>$value</literal> с &amp;. Това ще присвои по
-  <link linkend="language.references">референция</link>,
-  вместо да копира стойността.
+  За да можете да променяте директно елементите на даден масив в тялото на масива поставете
+  &amp; пред <literal>$value</literal>. Това ще присвои по
+  <link linkend="language.references">референция</link>.
   <informalexample>
    <programlisting role="php">
 <![CDATA[
@@ -79,9 +75,22 @@
 ]]>
    </programlisting>
   </informalexample>
-  Това е възможно единствено, в случай че обхожданият масив може да бъде указван с референция
-  (т.е. ако е променлива).
  </para>
+ <para>
+  Обръщането към <literal>$value</literal> по референция е възможно само ако масива
+  е референцируем (т.е. ако е променлива). Кодът по-долъ няма да работи:
+  <informalexample>
+   <programlisting role="php">
+<![CDATA[
+<?php
+foreach (array(1, 2, 3, 4) as &$value) {
+    $value = $value * 2;
+}
+?>
+]]>
+   </programlisting>
+  </informalexample>
+ </para>
  <warning>
   <para>
    Референцията между <literal>$value</literal> и последния елемент от масива
@@ -117,6 +126,8 @@
 ]]>
    </programlisting>
   </informalexample>
+ </para>
+ <para>
   Следните примери са също функционално идентични:
   <informalexample>
    <programlisting role="php">
@@ -197,6 +208,111 @@
    </programlisting>
   </informalexample>
  </para>
+
+ <sect2 xml:id="control-structures.foreach.list">
+  <title>Unpacking nested arrays with list()</title>
+  <?phpdoc print-version-for="foreach.list"?>
+
+  <para>
+   PHP 5.5 added the ability to iterate over an array of arrays and unpack the
+   nested array into loop variables by providing a <function>list</function>
+   as the value.
+  </para>
+
+  <para>
+   For example:
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$array = [
+    [1, 2],
+    [3, 4],
+];
+
+foreach ($array as list($a, $b)) {
+    // $a contains the first element of the nested array,
+    // and $b contains the second element.
+    echo "A: $a; B: $b\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+A: 1; B: 2
+A: 3; B: 4
+]]>
+    </screen>
+   </informalexample>
+  </para>
+
+  <para>
+   You can provide fewer elements in the <function>list</function> than there
+   are in the nested array, in which case the leftover array values will be
+   ignored:
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$array = [
+    [1, 2],
+    [3, 4],
+];
+
+foreach ($array as list($a)) {
+    // Note that there is no $b here.
+    echo "$a\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+1
+3
+]]>
+    </screen>
+   </informalexample>
+  </para>
+
+  <para>
+   A notice will be generated if there aren't enough array elements to fill
+   the <function>list</function>:
+
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$array = [
+    [1, 2],
+    [3, 4],
+];
+
+foreach ($array as list($a, $b, $c)) {
+    echo "A: $a; B: $b; C: $c\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+
+Notice: Undefined offset: 2 in example.php on line 7
+A: 1; B: 2; C:
+
+Notice: Undefined offset: 2 in example.php on line 7
+A: 3; B: 4; C:
+]]>
+    </screen>
+   </informalexample>
+  </para>
+ </sect2>
 </sect1>

 <!-- Keep this comment at the end of the file