reference/array/functions/array-diff.xml
c84024092aee02b51dd18b909af0f2ccbdd24f98
...
...
@@ -10,13 +10,12 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>array</type><methodname>array_diff</methodname>
13
-
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
14
-
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
15
-
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
13
+
<methodparam><type>array</type><parameter>array</parameter></methodparam>
14
+
<methodparam rep="repeat"><type>array</type><parameter>arrays</parameter></methodparam>
16
15
</methodsynopsis>
17
16
<para>
18
-
Compares <parameter>array1</parameter> against one or more other arrays and
19
-
returns the values in <parameter>array1</parameter> that are not present in
17
+
Compares <parameter>array</parameter> against one or more other arrays and
18
+
returns the values in <parameter>array</parameter> that are not present in
20
19
any of the other arrays.
21
20
</para>
22
21
</refsect1>
...
...
@@ -26,7 +25,7 @@
26
25
<para>
27
26
<variablelist>
28
27
<varlistentry>
29
-
<term><parameter>array1</parameter></term>
28
+
<term><parameter>array</parameter></term>
30
29
<listitem>
31
30
<para>
32
31
The array to compare from
...
...
@@ -34,18 +33,10 @@
34
33
</listitem>
35
34
</varlistentry>
36
35
<varlistentry>
37
-
<term><parameter>array2</parameter></term>
36
+
<term><parameter>arrays</parameter></term>
38
37
<listitem>
39
38
<para>
40
-
An array to compare against
41
-
</para>
42
-
</listitem>
43
-
</varlistentry>
44
-
<varlistentry>
45
-
<term><parameter>...</parameter></term>
46
-
<listitem>
47
-
<para>
48
-
More arrays to compare against
39
+
Arrays to compare against
49
40
</para>
50
41
</listitem>
51
42
</varlistentry>
...
...
@@ -57,7 +48,27 @@
57
48
&reftitle.returnvalues;
58
49
<para>
59
50
Returns an <type>array</type> containing all the entries from
60
-
<parameter>array1</parameter> that are not present in any of the other arrays.
51
+
<parameter>array</parameter> that are not present in any of the other arrays.
52
+
Keys in the <parameter>array</parameter> array are preserved.
53
+
</para>
54
+
</refsect1>
55
+

56
+
<refsect1 role="changelog">
57
+
&reftitle.changelog;
58
+
<para>
59
+
<informaltable>
60
+
<tgroup cols="2">
61
+
<thead>
62
+
<row>
63
+
<entry>&Version;</entry>
64
+
<entry>&Description;</entry>
65
+
</row>
66
+
</thead>
67
+
<tbody>
68
+
&array.changelog.require-only-one;
69
+
</tbody>
70
+
</tgroup>
71
+
</informaltable>
61
72
</para>
62
73
</refsect1>
63
74

...
...
@@ -91,20 +102,56 @@ Array
91
102
</screen>
92
103
</example>
93
104
</para>
105
+

106
+
<para>
107
+
<example>
108
+
<title><function>array_diff</function> example with non-matching types</title>
109
+
<para>
110
+
Two elements are considered equal if and only if
111
+
<literal>(string) $elem1 === (string) $elem2</literal>. That is,
112
+
when the <link linkend="language.types.string.casting">string representation</link> is the same.
113
+
</para>
114
+
<programlisting role="php">
115
+
<![CDATA[
116
+
<?php
117
+
// This will generate a Notice that an array cannot be cast to a string.
118
+
$source = [1, 2, 3, 4];
119
+
$filter = [3, 4, [5], 6];
120
+
$result = array_diff($source, $filter);
121
+

122
+
// Whereas this is fine, since the objects can cast to a string.
123
+
class S {
124
+
private $v;
125
+

126
+
public function __construct(string $v) {
127
+
$this->v = $v;
128
+
}
129
+

130
+
public function __toString() {
131
+
return $this->v;
132
+
}
133
+
}
134
+

135
+
$source = [new S('a'), new S('b'), new S('c')];
136
+
$filter = [new S('b'), new S('c'), new S('d')];
137
+

138
+
$result = array_diff($source, $filter);
139
+

140
+
// $result now contains one instance of S('a');
141
+
?>
142
+
]]>
143
+
</programlisting>
144
+
<para>
145
+
To use an alternate comparison function, see <function>array_udiff</function>.
146
+
</para>
147
+
</example>
148
+
</para>
94
149
</refsect1>
95
150

96
151
<refsect1 role="notes">
97
152
&reftitle.notes;
98
153
<note>
99
154
<para>
100
-
Two elements are considered equal if and only if
101
-
<literal>(string) $elem1 === (string) $elem2</literal>. In words:
102
-
when the string representation is the same.
103
-
<!-- TODO: example of it... -->
104
-
</para>
105
-
</note>
106
-
<note>
107
-
<para>
108
155
This function only checks one dimension of a n-dimensional
109
156
array. Of course you can check deeper dimensions by using
110
157
<literal>array_diff($array1[0], $array2[0]);</literal>.
...
...
@@ -117,6 +164,7 @@ Array
117
164
<para>
118
165
<simplelist>
119
166
<member><function>array_diff_assoc</function></member>
167
+
<member><function>array_udiff</function></member>
120
168
<member><function>array_intersect</function></member>
121
169
<member><function>array_intersect_assoc</function></member>
122
170
</simplelist>
123
171