svn: /phpdoc/ru/trunk/ language/oop5/decon.xml reference/quickhash/quickhashinthash/add.xml

Modified: phpdoc/ru/trunk/language/oop5/decon.xml
===================================================================
--- phpdoc/ru/trunk/language/oop5/decon.xml	2020-11-26 09:10:02 UTC (rev 351665)
+++ phpdoc/ru/trunk/language/oop5/decon.xml	2020-11-26 09:10:09 UTC (rev 351666)
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 351129 Maintainer: shein Status: ready -->
+<!-- EN-Revision: 351474 Maintainer: shein Status: ready -->
 <!-- Reviewed: yes -->
 <!-- $Revision$ -->
 <sect1 xml:id="language.oop5.decon" xmlns="http://docbook.org/ns/docbook">
@@ -7,12 +7,12 @@

  <sect2 xml:id="language.oop5.decon.constructor">
   <title>Конструктор</title>
-   <methodsynopsis xml:id="object.construct">
-    <type>void</type><methodname>__construct</methodname>
-    <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter><initializer>""</initializer></methodparam>
-   </methodsynopsis>
+  <methodsynopsis xml:id="object.construct">
+   <type>void</type><methodname>__construct</methodname>
+   <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter><initializer>""</initializer></methodparam>
+  </methodsynopsis>
   <para>
-   PHP 5 позволяет объявлять методы-конструкторы. Классы, в которых
+   PHP позволяет объявлять методы-конструкторы. Классы, в которых
    объявлен метод-конструктор, будут вызывать этот метод при каждом
    создании нового объекта, так что это может оказаться полезным,
    например, для инициализации какого-либо состояния объекта
@@ -31,7 +31,7 @@
    </simpara>
   </note>
   <example>
-   <title>Использование унифицированных конструкторов</title>
+   <title>Конструкторы при наследовании</title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -66,24 +66,6 @@
    </programlisting>
   </example>
   <para>
-   В целях обратной совместимости, если PHP 5 не может обнаружить
-   объявленный метод <link linkend="object.construct">__construct()</link>, то
-   вызов конструктора произойдет по устаревшей схеме, через обращение к методу,
-   имя которого соответствует имени класса. Может возникнуть только
-   одна проблема совместимости старого кода, если в нём присутствуют
-   классы с методами <link linkend="object.construct">__construct()</link>,
-   использующиеся для других целей.
-  </para>
-  <!-- Not using an entity because I want specific wording here, since we're
-   not deprecating constructors in general. -->
-  <warning>
-   <simpara>
-    Конструкторы старого типа объявлены <emphasis>УСТАРЕВШИМИ</emphasis> в PHP 7.0
-    и будут удалены в будущих версиях. В новом коде всегда используйте
-    <link linkend="object.construct">__construct()</link>.
-   </simpara>
-  </warning>
-  <para>
    В отличие от других методов, PHP не будет генерировать ошибку
    уровня <constant>E_STRICT</constant>, если
    <link linkend="object.construct">__construct()</link>
@@ -92,27 +74,186 @@
    <link linkend="object.construct">__construct()</link>.
   </para>
   <para>
-   Начиная с PHP 5.3.3, методы с именами, совпадающими с
-   последним элемeнтом имени класса, находящимся в пространстве имен,
-   больше не будут считаться конструкторами. Это изменение не влияет
-   на классы, не находящиеся в пространстве имен.
+   Конструкторы - это обычные методы, которые вызываются при
+   инстанциировании соответствующих объектов. Следовательно, они могут иметь
+   произвольное количество аргументов, которые могут быть обязательными, могут
+   быть типизированными и иметь значения по умолчанию. Аргументы конструктора
+   указываются в круглых скобках после имени класса.
   </para>
   <example>
-   <title>Конструкторы в классах, находящихся в пространстве имен</title>
+   <title>Использование аргументов в конструкторах</title>
    <programlisting role="php">
 <![CDATA[
 <?php
-namespace Foo;
-class Bar {
-    public function Bar() {
-        // рассматривается как конструктор в версиях PHP 5.3.0-5.3.2
-        // и как обычный метод, начиная с версии PHP 5.3.3
+class Point {
+    protected int $x;
+    protected int $y;
+
+    public function __construct(int $x, int $y = 0) {
+        $this->x = $x;
+        $this->y = $y;
     }
 }
+
+// Передаём оба параметра.
+$p1 = new Point(4, 5);
+// Передаём только обязательные параметры. Для $y используется значеие по умолчанию 0.
+$p2 = new Point(4);
+// Вызываем с именованными параметрами (начиная с PHP 8.0):
+$p3 = new Point(y: 5, x: 4);
 ?>
 ]]>
+   </programlisting>
+  </example>
+  <para>
+   Если у класса нет конструктора, или его конструктор не имеет обязательных парметров, скобки
+   после имени класса можно не писать.
+  </para>
+  <sect3>
+   <title>Конструкторы в старом стиле</title>
+   <para>
+    До PHP 8.0.0, классы в глобальном пространстве имен будут интерпретировать метод,
+    названный так же, как класс, как конструктор старого стиля. Этот синтаксис считается
+    устаревшим и будет вызывать ошибку уровня <constant>E_DEPRECATED</constant>, но
+    всё равно эти методы будут вызываться в качестве конструктора.
+    Если в классе присутствуют и <link linkend="object.construct">__construct()</link>
+    и метод с именем класса, то в качестве конструктора будет вызван
+    <link linkend="object.construct">__construct()</link>.
+   </para>
+   <para>
+    Для классов, находящихся в собственном пространстве имён и для всех классов, начиная с
+    PHP 8.0.0, метод названный по имени класса будет игнорироваться.
+   </para>
+   <para>В новом коде всегда используйте <link linkend="object.construct">__construct()</link>.
+   </para>
+  </sect3>
+  <sect3 xml:id="language.oop5.decon.constructor.promotion">
+   <title>Определение свойств объекта в конструкторе</title>
+   <para>
+    Начиная с PHP 8.0.0, параметры конструктора можно использовать для задания
+    соответствующих свойств объекта. Это довольно распространённая практика, присваивать
+    свойствам объекта параметры переданые в конструктор не производя никаких дополнительных
+    преобразований. Определение свойств класса в конструкторе позволяет значительно
+    сократить количество шаблонного кода для такого случая. Пример выше можно будет
+    переписать следующим образом.
+   </para>
+   <example>
+    <title>Использование определения свойств в конструкторе</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Point {
+    public function __construct(protected int $x, protected int $y = 0) {
+    }
+}
+]]>
     </programlisting>
-  </example>
+   </example>
+   <para>
+    Если декларация аргумент конструктора включает модификатор видимости, PHP интерпритирует
+    его одновременно и как аргумент конструктора и как свойство объекта и автоматически
+    присвоит свойству значение, переданное в конструктор. При этом, если не предполагается
+    какой либо дополнительной логики, тело конструктора можно оставить пустым. Код
+    конструктора выполнится после того, как все аргументы присвоятся всем соответствующим
+    свойствам.
+   </para>
+   <para>
+    В случае, если необходимо передать в конструктор аргументы, не являющиеся
+    свойствами объекта - это можно сделать. В конструкторе можно задавать как обычные
+    аргументы так и являющиеся свойствами объекта в любом порядке. Аргументы-свойства
+    никак не влияют на код, исполняемый в конструкторе.
+   </para>
+   <note>
+    <para>
+     Свойства объектов не могут быть типа <type>callable</type> в связи с неоднозначностью
+     которую они представляют для движка PHP. Соответственно и свойства определяемые
+     в конструкторе также не могут быть типа <type>callable</type>. Любые другие
+     <link linkend="language.types.declarations">декларации типов</link> допустимы.
+    </para>
+   </note>
+   <note>
+    <para>
+     <!-- This should be linked once attributes are documented. -->
+     Атрибуты, заданные для таких аргументов, будут применены как для них самих, так и для
+     соответствующих свойств.
+    </para>
+   </note>
+  </sect3>
+  <sect3 xml:id="language.oop5.decon.constructor.static">
+   <title>Статические методы создания объекта</title>
+   <para>
+    PHP поддерживает только один конструктор для класса. Однако в некоторых случаях есть
+    необходимость создавать объект разными путями в зависимости от разных входных даных.
+    Рекомендуемый способ - использовать статические методы как обёртки над конструктором.
+   </para>
+   <example>
+    <title>Использование статических методов для создания объектов</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Product {
+
+    private ?int $id;
+    private ?string $name;
+
+    private function __construct(?int $id = null, ?string $name = null) {
+        $this->id = $id;
+        $this->name = $name;
+    }
+
+    public static function fromBasicData(int $id, string $name): static {
+        $new = new static($id, $name);
+        return $new;
+    }
+
+    public static function fromJson(string $json): static {
+        $data = json_decode($json);
+        return new static($data['id'], $data['name']);
+    }
+
+    public static function fromXml(string $xml): static {
+        // Put your own logic here.
+        $data = convert_xml_to_array($xml);
+        $new = new static();
+        $new->id = $data['id'];
+        $new->name = $data['name'];
+        return $new;
+    }
+}
+
+$p1 = Product::fromBasicData(5, 'Widget');
+$p2 = Product::fromJson($some_json_string);
+$p3 = Product::fromXml($some_xml_string);
+]]>
+    </programlisting>
+   </example>
+   <para>
+    Конструктор можно сделать скрытым или защищённым для предотвращения его прямого вызова.
+    В таком случае для инстанциации останется только вариант со статическими методами.
+    Так как это методы того же класса, они имеют доступ ко всем его скрытым методам даже
+    если они относятся к разным экземплярам класса. Скрытый конструктор опционален и
+    может присутствовать или отсутствовать по необходимости.
+   </para>
+   <para>
+    В примере выше три публичных статических метода демонстрируют различные способы
+    создания экземпляра объекта.
+   </para>
+   <simplelist>
+    <member><code>fromBasicData()</code> принимает явные параметры, создаёт экземпляр
+     класса через конструктор и возвращает объект.</member>
+    <member><code>fromJson()</code> принимает JSON строку, производит над ней некоторые
+     преобразования, извлекает данные необходимые для создания объекта и, так же как и
+     предыдущий метод, вызывает конструктор и возвращает созданный объект.</member>
+    <member><code>fromXml()</code> принимает XML строку, извлекает нужные данные и, так
+     как в конструкторе нет обязательных параметров, вызывает его без них. После этого, так
+     как ему доступны скрытые свойства, он присваевает им значения напрямую. После чего
+     возвращает готовый объект.</member>
+   </simplelist>
+   <para>
+    Во всех трёх случаях, ключевое слово <code>static</code> транслируется в имя класса
+    в котором этот код вызывается. В нашем случае <code>Product</code>.
+   </para>
+  </sect3>
  </sect2>

  <sect2 xml:id="language.oop5.decon.destructor">
@@ -147,34 +288,34 @@
 $obj = new MyDestructableClass();

 ]]>
-    </programlisting>
-   </example>
+   </programlisting>
+  </example>
+  <para>
+   Как и в случае с конструкторами, деструкторы, объявленные
+   в родительском классе, не будут вызываться автоматически.
+   Для вызова деструктора родительского класса,
+   требуется вызвать <function>parent::__destruct</function> в
+   теле деструктора дочернего класса. Подобно конструкторам, дочерний класс может унаследовать
+   деструктор из родительского класса, если он не определен в нем.
+  </para>
+  <para>
+   Деструктор будет вызываться даже в том случае, если скрипт был остановлен с
+   помощью функции <function>exit</function>. Вызов <function>exit</function>
+   в деструкторе предотвратит запуск всех последующих функций завершения.
+  </para>
+  <note>
    <para>
-    Как и в случае с конструкторами, деструкторы, объявленные
-    в родительском классе, не будут вызываться автоматически.
-    Для вызова деструктора родительского класса,
-    требуется вызвать <function>parent::__destruct</function> в
-    теле деструктора дочернего класса. Подобно конструкторам, дочерний класс может унаследовать
-    деструктор из родительского класса, если он не определен в нем.
+    Деструкторы, вызываемые при завершении скрипта, вызываются после отправки
+    HTTP-заголовков. Рабочая директория во время фазы завершения скрипта
+    может отличаться в некоторых SAPI (например, в Apache).
    </para>
+  </note>
+  <note>
    <para>
-    Деструктор будет вызываться даже в том случае, если скрипт был остановлен с
-    помощью функции <function>exit</function>. Вызов <function>exit</function>
-    в деструкторе предотвратит запуск всех последующих функций завершения.
+    Попытка выбросить исключение из деструктора (вызываемого во время
+    завершения скрипта) вызывает фатальную ошибку.
    </para>
-   <note>
-    <para>
-     Деструкторы, вызываемые при завершении скрипта, вызываются после отправки
-     HTTP-заголовков. Рабочая директория во время фазы завершения скрипта
-     может отличаться в некоторых SAPI (например, в Apache).
-    </para>
-   </note>
-   <note>
-    <para>
-     Попытка выбросить исключение из деструктора (вызываемого во время
-     завершения скрипта) вызывает фатальную ошибку.
-    </para>
-   </note>
+  </note>
  </sect2>

 </sect1>

Added: phpdoc/ru/trunk/reference/quickhash/quickhashinthash/add.xml
===================================================================
--- phpdoc/ru/trunk/reference/quickhash/quickhashinthash/add.xml	                        (rev 0)
+++ phpdoc/ru/trunk/reference/quickhash/quickhashinthash/add.xml	2020-11-26 09:10:09 UTC (rev 351666)
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 321911 Maintainer: rjhdby Status: ready -->
+<!-- Reviewed: no -->
+
+<refentry xml:id="quickhashinthash.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>QuickHashIntHash::add</refname>
+  <refpurpose>Добавить элемент в хэш</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>bool</type><methodname>QuickHashIntHash::add</methodname>
+   <methodparam><type>int</type><parameter>key</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>value</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Добавляет элемент в хэш и возвращает &true; или &false; в зависимости от успешности операции.
+   По умолчанию, добавление происходит всегда, если при создании хэша не использовался флаг
+   QuickHashIntHash::CHECK_FOR_DUPES.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>key</parameter></term>
+     <listitem>
+      <para>
+       Ключ добавляемой записи.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>value</parameter></term>
+     <listitem>
+      <para>
+       Опциональное значение. Если не задано, то будет использоваться <literal>1</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   В случае удачного добавления возвращает &true;. В случае неудачного - &false;.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Пример использования <function>QuickHashIntHash::add</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo "without dupe checking\n";
+$hash = new QuickHashIntHash( 1024 );
+var_dump( $hash->exists( 4 ) );
+var_dump( $hash->get( 4 ) );
+var_dump( $hash->add( 4, 22 ) );
+var_dump( $hash->exists( 4 ) );
+var_dump( $hash->get( 4 ) );
+var_dump( $hash->add( 4, 12 ) );
+
+echo "\nwith dupe checking\n";
+$hash = new QuickHashIntHash( 1024, QuickHashIntHash::CHECK_FOR_DUPES );
+var_dump( $hash->exists( 4 ) );
+var_dump( $hash->get( 4 ) );
+var_dump( $hash->add( 4, 78 ) );
+var_dump( $hash->exists( 4 ) );
+var_dump( $hash->get( 4 ) );
+var_dump( $hash->add( 4, 9 ) );
+
+echo "\ndefault value\n";
+var_dump( $hash->add( 5 ) );
+var_dump( $hash->get( 5 ) );
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+without dupe checking
+bool(false)
+bool(false)
+bool(true)
+bool(true)
+int(22)
+bool(true)
+
+with dupe checking
+bool(false)
+bool(false)
+bool(true)
+bool(true)
+int(78)
+bool(false)
+
+default value
+bool(true)
+int(1)
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->


Property changes on: phpdoc/ru/trunk/reference/quickhash/quickhashinthash/add.xml
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
\ No newline at end of property