[PHP-DOC] cvs: phpdoc /de/functions array.xml From: Wolfgang Drews (drews <email protected>)
Date: 07/12/00

drews Wed Jul 12 04:57:58 2000 EDT

  Modified files:
    /phpdoc/de/functions array.xml
  Log:
  Added:
  function.array-multisort
  function.array-merge-recursive
  function.array-rand
  (updated from english manual)
  
  translation required
  --> german tree version is up2date now
  
Index: phpdoc/de/functions/array.xml
diff -u phpdoc/de/functions/array.xml:1.7 phpdoc/de/functions/array.xml:1.8
--- phpdoc/de/functions/array.xml:1.7 Sun Jul 2 02:38:47 2000
+++ phpdoc/de/functions/array.xml Wed Jul 12 04:57:58 2000
@@ -217,6 +217,165 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.array-merge-recursive">
+ <refnamediv>
+ <refname>array_merge_recursive</refname>
+ <refpurpose>Merge two or more arrays recursively</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>array_merge_recursive</function></funcdef>
+ <paramdef>array <parameter>array1</parameter></paramdef>
+ <paramdef>array <parameter>array2</parameter></paramdef>
+ <paramdef>
+ <parameter><optional> ...</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>array_merge_recursive</function> merges the elements of
+ two or more arrays together so that the values of one are appended
+ to the end of the previous one. It returns the resulting array.
+ </para>
+ <para>
+ If the input arrays have the same string keys, then the values for
+ these keys are merged together into an array, and this is done
+ recursively, so that if one of the values is an array itself, the
+ function will merge it with a corresponding entry in another array
+ too. If, however, the arrays have the same numeric key, the later
+ value will not overwrite the original value, but will be appended.
+ </para>
+ <para>
+ <example>
+ <title><function>array_merge_recursive</function> example</title>
+ <programlisting role="php">
+$ar1 = array("color" => array("favorite" => "red"), 5);
+$ar2 = array(10, "color" => array("favorite" => "green", "blue"));
+$result = array_merge_recursive($ar1, $ar2);
+ </programlisting>
+ <para>
+ Resulting array will be array("color" => array("favorite" =>
+ array("red", "green"), "blue"), 5, 10).
+ </para>
+ </example>
+ </para>
+ <para>
+ See also <function>array_merge</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.array-multisort">
+ <refnamediv>
+ <refname>array_multisort</refname>
+ <refpurpose>Sort multiple or multi-dimensional arrays</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>array_multisort</function></funcdef>
+ <paramdef>array <parameter>ar1</parameter></paramdef>
+ <paramdef>mixed
+ <parameter><optional>arg</optional></parameter>
+ </paramdef>
+ <paramdef>
+ <parameter><optional>...</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>array_multisort</function> can be used to sort several
+ arrays at once or a multi-dimensional array according by one of
+ more dimensions. It maintains key association when sorting.
+ </para>
+
+ <para>
+ The input arrays are treated as columns of a table to be sorted
+ by rows - this resembles the functionality of SQL ORDER BY
+ clause. The first array is the primary one to sort by. The rows
+ (values) in that array that compare the same are sorted by the
+ next input array, and so on.
+ </para>
+
+ <para>
+ The argument structure of this function is a bit unusual, but
+ flexible. The very first argument has to be an
+ array. Subsequently, each argument can be either an array or a
+ sorting flag from the following lists.
+ </para>
+
+ <para>
+ Sorting order flags:
+ <itemizedlist>
+ <listitem>
+ <simpara>SORT_ASC - sort in ascending order</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_DESC - sort in descending order</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Sorting type flags:
+ <itemizedlist>
+ <listitem>
+ <simpara>SORT_REGULAR - compare items normally</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_NUMERIC - compare items numerically</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_STRING - compare items as strings</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ No two sorting flags of the same type can be specified after each
+ array. The sortings flags specified after an array argument apply
+ only to that array - they are reset to default SORT_ASC and
+ SORT_REGULAR after before each new array argument.
+ </para>
+
+ <para>
+ Returns true on success, false on failure.
+ </para>
+
+ <example>
+ <title>Sorting multiple arrays</title>
+ <programlisting role="php">
+$ar1 = array("10", 100, 100, "a");
+$ar2 = array(1, 3, "2", 1);
+array_multisort($ar1, $ar2);
+ </programlisting>
+ <para>
+ In this example, after sorting, the first array will contain 10,
+ "a", 100, 100. The second array will contain 1, 1, 2, "3". The
+ entries in the second array corresponding to the identical
+ entries in the first array (100 and 100) were sorted as well.
+ </para>
+ </example>
+
+ <example>
+ <title>Sorting multi-dimensional array</title>
+ <programlisting role="php">
+$ar = array(array("10", 100, 100, "a"), array(1, 3, "2", 1));
+array_multisort($ar[0], SORT_ASC, SORT_STRING, $ar[1], SORT_NUMERIC, SORT_DESC);
+ </programlisting>
+ <para>
+ In this example, after sorting, the first array will contain 10,
+ 100, 100, "a" (it was sorted as strings in ascending order), and
+ the second one will contain 1, 3, "2", 1 (sorted as numbers, in
+ descending order).
+ </para>
+ </example>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.array-pad">
    <refnamediv>
     <refname>array_pad</refname>
@@ -364,6 +523,57 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.array-rand">
+ <refnamediv>
+ <refname>array_rand</refname>
+ <refpurpose>Pick one or more random entries out of an array</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>mixed <function>array_rand</function></funcdef>
+ <paramdef>array <parameter>input</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>num_req</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>array_rand</function> is rather useful when you want to
+ pick one or more random entries out of an array. It takes an
+ <parameter>input</parameter> array and an optional argument
+ <parameter>num_req</parameter> which specifies how many entries you
+ want to pick - if not specified, it defaults to 1.
+ </para>
+
+ <para>
+ If you are picking only one entry, <function>array_rand</function>
+ returns the key for a random entry. Otherwise, it returns an array
+ of keys for the random entries. This is done so that you can pick
+ random keys as well as values out of the array.
+ </para>
+
+ <para>
+ Don't forget to call <function>srand</function> to seed the random
+ number generator.
+ </para>
+
+ <para>
+ <example>
+ <title><function>array_rand</function> example</title>
+ <programlisting role="php">
+srand((double)microtime() * 10000000);
+$input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
+$rand_keys = array_rand($input, 2);
+print $input[$rand_keys[0]]."\n";
+print $input[$rand_keys[1]]."\n";
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.array-reverse">
    <refnamediv>
     <refname>array_reverse</refname>