- Document 4 new array functions.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@164405 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Dave Barr 2004-07-27 04:15:58 +00:00
parent c30a4d4d5e
commit a456251039
4 changed files with 438 additions and 0 deletions

View file

@ -0,0 +1,102 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.array-diff-key">
<refnamediv>
<refname>array_diff_key</refname>
<refpurpose>Computes the difference of arrays using keys for comparison</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>array_diff_key</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_diff_key</function> returns an array
containing all the values of <parameter>array1</parameter>
that have keys that are not present in any of the other arguments.
Note that the associativity is preserved. This function is like
<function>array_diff</function> except the comparison is done on the
keys instead of the values.
</para>
<para>
<example>
<title><function>array_diff_key</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);
var_dump(array_diff_key($array1, $array2));
?>
]]>
</programlisting>
<para>
The printout of the above program will be:
</para>
<screen>
<![CDATA[
array(2) {
["red"]=>
int(2)
["purple"]=>
int(4)
}
]]>
</screen>
</example>
</para>
<simpara>
The two keys from the <literal>key =&gt; value</literal> pairs are
considered equal only if
<literal>(string) $key1 === (string) $key2 </literal>. In other words
a strict type check is executed so the string representation must be
the same.
</simpara>
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
array. Of course you can check deeper dimensions by using
<literal>array_diff_key($array1[0], $array2[0]);</literal>.
</simpara>
</note>
<para>
See also <function>array_diff</function>,
<function>array_udiff</function>
<function>array_diff_assoc</function>,
<function>array_diff_uassoc</function>,
<function>array_udiff_assoc</function>,
<function>array_udiff_uassoc</function>,
<function>array_diff_ukey</function>,
<function>array_intersect</function>,
<function>array_intersect_assoc</function>,
<function>array_intersect_uassoc</function>,
<function>array_intersect_key</function> and
<function>array_intersect_ukey</function>.
</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:"../../../../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
-->

View file

@ -0,0 +1,119 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.array-diff-ukey">
<refnamediv>
<refname>array_diff_ukey</refname>
<refpurpose>Computes the difference of arrays using a callback function on the keys for comparison</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>array_diff_ukey</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
<methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_diff_ukey</function> returns an array
containing all the values of <parameter>array1</parameter>
that have keys that are not present in any of the other arguments.
Note that the associativity is preserved. This function is like
<function>array_diff</function> except the comparison is done on the
keys instead of the values.
</para>
<para>
This comparison is done by a user supplied callback function.
It must return an integer less than, equal to, or greater than zero if the
first key is considered to be respectively less than, equal to, or
greater than the second.
</para>
<para>
<example>
<title><function>array_diff_ukey</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
function key_compare_func($key1, $key2)
{
if ($key1 == $key2)
return 0;
else if ($key1 > $key2)
return 1;
else
return -1;
}
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);
var_dump(array_diff_ukey($array1, $array2, 'key_compare_func'));
?>
]]>
</programlisting>
<para>
The printout of the above program will be:
</para>
<screen>
<![CDATA[
array(2) {
["red"]=>
int(2)
["purple"]=>
int(4)
}
]]>
</screen>
</example>
</para>
<simpara>
The two keys from the <literal>key =&gt; value</literal> pairs are
considered equal only if
<literal>(string) $key1 === (string) $key2 </literal>. In other words
a strict type check is executed so the string representation must be
the same.
</simpara>
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
array. Of course you can check deeper dimensions by using
<literal>array_diff_ukey($array1[0], $array2[0], 'callback_func');</literal>.
</simpara>
</note>
<para>
See also <function>array_diff</function>,
<function>array_udiff</function>
<function>array_diff_assoc</function>,
<function>array_diff_uassoc</function>,
<function>array_udiff_assoc</function>,
<function>array_udiff_uassoc</function>,
<function>array_diff_key</function>,
<function>array_intersect</function>,
<function>array_intersect_assoc</function>,
<function>array_intersect_uassoc</function>,
<function>array_intersect_key</function> and
<function>array_intersect_ukey</function>.
</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:"../../../../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
-->

View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.array-intersect-key">
<refnamediv>
<refname>array_intersect_key</refname>
<refpurpose>Computes the intersection of arrays using keys for comparison</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>array_intersect_key</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_intersect_key</function> returns an array
containing all the values of <parameter>array1</parameter>
which have matching keys that are present in all the arguments.
</para>
<para>
<example>
<title><function>array_intersect_key</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);
var_dump(array_intersect_key($array1, $array2));
?>
]]>
</programlisting>
<para>
The printout of the above program will be:
</para>
<screen>
<![CDATA[
array(2) {
["blue"]=>
int(1)
["green"]=>
int(3)
})
]]>
</screen>
</example>
</para>
<para>
In our example you see that only the keys <literal>'blue'</literal>
and <literal>'green'</literal> are present in both arrays and thus
returned. Also notice that the values for the keys
<literal>'blue'</literal> and <literal>'green'</literal> differ between
the two arrays. A match still occurs because only the keys are checked.
The values returned are those of <parameter>array1</parameter>.
</para>
<para>
The two keys from the <literal>key =&gt; value</literal> pairs are
considered equal only if
<literal>(string) $key1 === (string) $key2 </literal>. In other words
a strict type check is executed so the string representation must be
the same.
</para>
<para>
See also <function>array_diff</function>,
<function>array_udiff</function>
<function>array_diff_assoc</function>,
<function>array_diff_uassoc</function>,
<function>array_udiff_assoc</function>,
<function>array_udiff_uassoc</function>,
<function>array_diff_key</function>,
<function>array_diff_ukey</function>,
<function>array_intersect</function>,
<function>array_intersect_assoc</function>,
<function>array_intersect_uassoc</function> and
<function>array_intersect_ukey</function>.
</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:"../../../../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
-->

View file

@ -0,0 +1,117 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.array-intersect-ukey">
<refnamediv>
<refname>array_intersect_ukey</refname>
<refpurpose>Computes the intersection of arrays using a callback function on the keys for comparison</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>array_intersect_ukey</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
<methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_intersect_ukey</function> returns an array
containing all the values of <parameter>array1</parameter>
which have matching keys that are present in all the arguments.
</para>
<para>
This comparison is done by a user supplied callback function.
It must return an integer less than, equal to, or greater than zero if the
first key is considered to be respectively less than, equal to, or
greater than the second.
</para>
<para>
<example>
<title><function>array_intersect_ukey</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
function key_compare_func($key1, $key2)
{
if ($key1 == $key2)
return 0;
else if ($key1 > $key2)
return 1;
else
return -1;
}
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);
var_dump(array_intersect_ukey($array1, $array2, 'key_compare_func'));
?>
]]>
</programlisting>
<para>
The printout of the above program will be:
</para>
<screen>
<![CDATA[
array(2) {
["blue"]=>
int(1)
["green"]=>
int(3)
})
]]>
</screen>
</example>
</para>
<para>
In our example you see that only the keys <literal>'blue'</literal>
and <literal>'green'</literal> are present in both arrays and thus
returned. Also notice that the values for the keys
<literal>'blue'</literal> and <literal>'green'</literal> differ between
the two arrays. A match still occurs because only the keys are checked.
The values returned are those of <parameter>array1</parameter>.
</para>
<para>
The two keys from the <literal>key =&gt; value</literal> pairs are
considered equal only if
<literal>(string) $key1 === (string) $key2 </literal>. In other words
a strict type check is executed so the string representation must be
the same.
</para>
<para>
See also <function>array_diff</function>,
<function>array_udiff</function>
<function>array_diff_assoc</function>,
<function>array_diff_uassoc</function>,
<function>array_udiff_assoc</function>,
<function>array_udiff_uassoc</function>,
<function>array_diff_key</function>,
<function>array_diff_ukey</function>,
<function>array_intersect</function>,
<function>array_intersect_assoc</function>,
<function>array_intersect_uassoc</function> and
<function>array_intersect_key</function>.
</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:"../../../../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
-->