Simplify array_replace description and add nested array example (#3809)

Based on discussion at PR #1470

Author: jimwins

reference/array/functions/array-replace.xml

@@ -13,18 +13,13 @@
    <methodparam rep="repeat"><type>array</type><parameter>replacements</parameter></methodparam>
   </methodsynopsis>
   <para>
-   <function>array_replace</function> replaces the values of
-   <parameter>array</parameter> with values having the same keys in each of the following
-   arrays. If a key from the first array exists in the second array, its value
-   will be replaced by the value from the second array. If the key exists in the
-   second array, and not the first, it will be created in the first array.
-   If a key only exists in the first array, it will be left as is.
-   If several arrays are passed for replacement, they will be processed
-   in order, the later arrays overwriting the previous values.
+   <function>array_replace</function> creates a new array and assigns items into
+   it for each key in each of the provided arrays. If a key appears in multiple
+   input arrays, the value from the right-most input array will be used.
   </para>
   <para>
-   <function>array_replace</function> is not recursive : it will replace
-   values in the first array by whatever type is in the second array.
+   <function>array_replace</function> does not process elements items recursively,
+   it replaces the entire value for each key when it does a replacement.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -70,21 +65,59 @@ $replacements = array(0 => "pineapple", 4 => "cherry");
 $replacements2 = array(0 => "grape");
 
 $basket = array_replace($base, $replacements, $replacements2);
-print_r($basket);
+var_dump($basket);
 ?>
 ]]>
     </programlisting>
     &example.outputs;
     <screen role="php">
 <![CDATA[
-Array
-(
-    [0] => grape
-    [1] => banana
-    [2] => apple
-    [3] => raspberry
-    [4] => cherry
-)
+array(5) {
+  [0]=>
+  string(5) "grape"
+  [1]=>
+  string(6) "banana"
+  [2]=>
+  string(5) "apple"
+  [3]=>
+  string(9) "raspberry"
+  [4]=>
+  string(6) "cherry"
+}
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Example of how nested arrays are handled</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$base = [ 'citrus' => [ 'orange', 'lemon' ], 'pome' => [ 'apple' ] ];
+$replacements = [ 'citrus' => [ 'grapefruit' ] ];
+$replacements2 = [ 'citrus' => [ 'kumquat', 'citron' ], 'pome' => [ 'loquat' ] ];
+
+$basket = array_replace($base, $replacements, $replacements2);
+var_dump($basket);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+array(2) {
+  ["citrus"]=>
+  array(2) {
+    [0]=>
+    string(7) "kumquat"
+    [1]=>
+    string(6) "citron"
+  }
+  ["pome"]=>
+  array(1) {
+    [0]=>
+    string(6) "loquat"
+  }
+}
 ]]>
     </screen>
    </example>