Translate Ds\Hashable (#1160)

reference/ds/ds/hashable/equals.xml

@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: dd07341fae2c414adc1f700be0890ff32e8daab4 Maintainer: Fan2Shrek Status: ready -->
+<!-- Reviewed: yes -->
+<refentry xml:id="ds-hashable.equals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Ds\Hashable::equals</refname>
+  <refpurpose>Détermine si un objet est égal à l'instance actuelle</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>bool</type><methodname>Ds\Hashable::equals</methodname>
+   <methodparam><type>object</type><parameter>obj</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+    Détermine si un autre objet est égal à l'instance actuelle.
+  </para>
+
+  <para>
+    Cette méthode permet d'utiliser des objets comme clés dans des structures telles que
+    <classname>Ds\Map</classname> et <classname>Ds\Set</classname>, ou toute autre
+    structure de recherche qui respecte cette interface.
+  </para>
+
+  <note>
+    <para>
+        Il est garanti que <parameter>obj</parameter> est une instance de la même classe.
+    </para>
+  </note>
+
+  <caution>
+    <para>
+        Il est important que les objets qui sont égaux aient également la même valeur de hachage.
+        Voir <function>Ds\Hashable::hash</function>.
+    </para>
+  </caution>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>obj</parameter></term>
+    <listitem>
+     <para>
+        L'objet à comparer à l'instance actuelle, qui est toujours une instance de
+        la même classe.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+    &true; si les objets sont égaux, sinon &false;.
+  </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
+-->

reference/ds/ds/hashable/hash.xml

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: dd07341fae2c414adc1f700be0890ff32e8daab4 Maintainer: Fan2Shrek Status: ready -->
+<!-- Reviewed: yes -->
+<refentry xml:id="ds-hashable.hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Ds\Hashable::hash</refname>
+  <refpurpose>Renvoie une valeur scalaire à utiliser comme valeur de hachage</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>mixed</type><methodname>Ds\Hashable::hash</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+    Renvoie une valeur scalaire à utiliser comme valeur de hachage des objets.
+  </para>
+  <para>
+    Tant que la valeur de hachage ne définit pas l'égalité, tous les objets qui sont égaux selon <function>Ds\Hashable::equals</function>
+    doivent avoir la même valeur de hachage. Les valeurs de hachage des objets égaux n'ont pas à être uniques, par exemple
+    vous pourriez simplement retourner &true; pour tous les objets et rien ne se casserait - la seule
+    implication serait que les tables de hachage se transformeraient en listes chaînées car tous
+    vos objets seront hachés dans le même seau. Il est donc très important
+    que vous choisissiez une bonne valeur de hachage, telle qu'un ID ou une adresse e-mail.
+ </para>
+
+  <para>
+    Cette méthode permet d'utiliser des objets comme clés dans des structures telles que
+    <classname>Ds\Map</classname> et <classname>Ds\Set</classname>, ou toute autre
+    structure de recherche qui respecte cette interface.
+  </para>
+
+  <caution>
+    <para>
+        Ne choisissez pas une valeur qui pourrait changer dans l'objet, comme une propriété publique.
+        Les recherches dans les tables de hachage échoueraient car le hachage a changé.
+    </para>
+  </caution>
+
+  <caution>
+    <para>
+        Tous les objets qui sont égaux doivent avoir la même valeur de hachage.
+    </para>
+  </caution>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+    Une valeur scalaire à utiliser comme valeur de hachage de cet objet.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Exemple de <function>Ds\Hashable::hash</function></title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+class HashableObject implements \Ds\Hashable
+{
+    private $name;
+    private $email;
+
+    public function __construct($name, $email)
+    {
+        $this->name  = $name;
+        $this->email = $email;
+    }
+
+    /**
+     * Doit renvoyer la même valeur pour tous les objets égaux, mais n'a pas à
+     * être unique. Cette valeur ne sera pas utilisée pour déterminer l'égalité.
+     */
+    public function hash()
+    {
+        return $this->email;
+    }
+
+    /**
+     * Détermine l'égalité, généralement lors d'une recherche dans une table de hachage pour déterminer
+     * si la clé du seau correspond à la clé de recherche. Le hachage doit être égal si
+     * les objets sont égaux, sinon cette détermination ne serait pas atteinte.
+     */
+    public function equals($obj): bool
+    {
+        return $this->name  === $obj->name
+            && $this->email === $obj->email;
+    }
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </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
+-->