jmcastagnetto Tue Mar 27 04:57:20 2001 EDT
Modified files:
/phpdoc/en/functions array.xml
Log:
documentation of array_filter, array_map, and array_reduce
Index: phpdoc/en/functions/array.xml
diff -u phpdoc/en/functions/array.xml:1.61 phpdoc/en/functions/array.xml:1.62
--- phpdoc/en/functions/array.xml:1.61 Fri Mar 16 22:14:56 2001
+++ phpdoc/en/functions/array.xml Tue Mar 27 04:57:19 2001
@@ -200,6 +200,62 @@
</refsect1>
</refentry>
+ <refentry id="function.array-filter">
+ <refnamediv>
+ <refname>array_filter</refname>
+ <refpurpose>Filters elements of an array using a callback function</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>array_filter</function></funcdef>
+ <paramdef>array <parameter>input</parameter></paramdef>
+ <paramdef>mixed
+ <parameter><optional>callback</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>Array_filter</function> returns an array
+ containing all the elements of <parameter>input</parameter>
+ filtered according a callback function. If the
+ <parameter>input</parameter> is an associative array
+ the keys are preserved.
+ </para>
+ <para>
+ <example>
+ <title><function>Array_filter</function> example</title>
+ <programlisting role="php">
+function odd($var) {
+ return ($var % 2 == 1);
+}
+
+function even($var) {
+ return ($var % 2 == 0);
+}
+
+$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5);
+$array2 = array (6, 7, 8, 9, 10, 11, 12);
+
+$odd_arr = array_filter($array1, "odd");
+$even_arr = array_filter($array2, "even");
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ This makes <varname>$odd_arr</varname> have
+ <literal>array ("a"=>1, "c"=>3, "e"=>5);</literal>,
+ and <varname>$even_arr</varname> have
+ <literal>array (6, 8, 10, 12);</literal>,
+ </para>
+ <para>
+ See also <function>array_map</function>,
+ <function>array_reduce</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
<refentry id="function.array-flip">
<refnamediv>
<refname>array_flip</refname>
@@ -342,6 +398,184 @@
</refsect1>
</refentry>
+ <refentry id="function.array-map">
+ <refnamediv>
+ <refname>array_map</refname>
+ <refpurpose>Applies the callback to the elements of the given arrays</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>array_map</function></funcdef>
+ <paramdef>mixed <parameter>callback</parameter></paramdef>
+ <paramdef>array <parameter>arr1</parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>arr2...</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>Array_map</function> returns an array
+ containing all the elements of <parameter>arr1</parameter>
+ after applying the callback function to each one.
+ The number of parameters that the callback function accepts should
+ match the number of arrays passed to the <function>array_map</function>
+ </para>
+ <para>
+ <example>
+ <title><function>Array_map</function> example</title>
+ <programlisting role="php">
+function cube($n) {
+ return $n*$n*$n;
+}
+
+$a = array(1, 2, 3, 4, 5);
+$b = array_map("cube", $a);
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ This will result in <varname>$b</varname> containing
+ <literal>array (1, 8, 27, 64, 125);</literal>
+ </para>
+ <para>
+ <example>
+ <title><function>Array_filter</function> - using more arrays</title>
+ <programlisting role="php">
+function show_Spanish($n, $m) {
+ return "The number $n is called $m in Spanish";
+}
+
+function map_Spanish($n, $m) {
+ return array ($n => $m);
+}
+
+$a = array(1, 2, 3, 4, 5);
+$b = array("uno", "dos", "tres", "cuatro", "cinco");
+
+$c = array_map("show_Spanish", $a, $b);
+
+print_r($c);
+
+// will output:
+// Array
+// (
+// [0] => The number 1 is called uno in Spanish
+// [1] => The number 2 is called dos in Spanish
+// [2] => The number 3 is called tres in Spanish
+// [3] => The number 4 is called cuatro in Spanish
+// [4] => The number 5 is called cinco in Spanish
+// )
+
+$d = array_map("map_Spanish", $a , $b);
+
+print_r($d);
+
+// will output:
+// Array
+// (
+// [0] => Array
+// (
+// [1] => uno
+// )
+//
+// [1] => Array
+// (
+// [2] => dos
+// )
+//
+// [2] => Array
+// (
+// [3] => tres
+// )
+//
+// [3] => Array
+// (
+// [4] => cuatro
+// )
+//
+// [4] => Array
+// (
+// [5] => cinco
+// )
+//
+// )
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Usually when using two or more arrays, they should be of equal length
+ because the callback function is applied in parallel to the corresponding
+ elements.
+ If the arrays are of unequal length, the shortest one will be extended
+ with empty elements.
+ </para>
+ <para>
+ An interesting use of this function is to construct an array of arrays,
+ which can be easily performed by using <literal>null</literal>
+ as the name of the callback function
+ </para>
+ <para>
+ <example>
+ <title><function>Array_map</function> - creating an array of arrays</title>
+ <programlisting role="php">
+$a = array(1, 2, 3, 4, 5);
+$b = array("one", "two", "three", "four", "five");
+$c = array("uno", "dos", "tres", "cuatro", "cinco");
+
+$d = array_map(null, $a, $b, $c);
+print_r($d);
+
+// will output:
+// Array
+// (
+// [0] => Array
+// (
+// [0] => 1
+// [1] => one
+// [2] => uno
+// )
+//
+// [1] => Array
+// (
+// [0] => 2
+// [1] => two
+// [2] => dos
+// )
+//
+// [2] => Array
+// (
+// [0] => 3
+// [1] => three
+// [2] => tres
+// )
+//
+// [3] => Array
+// (
+// [0] => 4
+// [1] => four
+// [2] => cuatro
+// )
+//
+// [4] => Array
+// (
+// [0] => 5
+// [1] => five
+// [2] => cinco
+// )
+//
+// )
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ See also <function>array_filter</function>,
+ <function>array_reduce</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
<refentry id="function.array-merge">
<refnamediv>
<refname>array_merge</refname>
@@ -787,6 +1021,68 @@
The second parameter was added in PHP 4.0.3.
</para>
</note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.array-reduce">
+ <refnamediv>
+ <refname>array_reduce</refname>
+ <refpurpose>
+ Iteratively reduce the array to a single value using a callback function
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>mixed <function>array_reduce</function></funcdef>
+ <paramdef>array <parameter>input</parameter></paramdef>
+ <paramdef>mixed <parameter>callback</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>initial</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>Array_reduce</function> applies iteratively the
+ <parameter>callback</parameter> function to the elements of the
+ array <parameter>input</parameter>, so as to reduce the array to
+ a single value. If the optional <parameter>intial</parameter> is
+ avaliable, it will be used at the beginning of the process, or as
+ a final result in case the array is empty.
+ </para>
+ <para>
+ <example>
+ <title><function>Array_reduce</function> example</title>
+ <programlisting role="php">
+function rsum($v, $w) {
+ $v += $w;
+ return $v;
+}
+
+function rmul($v, $w) {
+ $v *= $w;
+ return $v;
+}
+
+$a = array(1, 2, 3, 4, 5);
+$x = array();
+$b = array_reduce($a, "rsum");
+$c = array_reduce($a, "rmul", 10);
+$d = array_reduce($x, "rsum", 1);
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ This will result in <varname>$b</varname> containing
+ <literal>15</literal>, <varname>$c</varname> containing
+ <literal>1200</literal> (= 1*2*3*4*5*10), and <varname>$d</varname>
+ containing <literal>1</literal>.
+ </para>
+ <para>
+ See also <function>array_filter</function>,
+ <function>array_map</function>.
+ </para>
</refsect1>
</refentry>
