<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.create-function" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>create_function</refname>
  <refpurpose>Create an anonymous (lambda-style) function</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  &warn.deprecated.function-7-2-0;
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>create_function</methodname>
   <methodparam><type>string</type><parameter>args</parameter></methodparam>
   <methodparam><type>string</type><parameter>code</parameter></methodparam>
  </methodsynopsis>
  <para>
   Creates an anonymous function from the parameters passed, and
   returns a unique name for it.
  </para>
  <caution>
   <para>
    This function internally performs an <function>eval</function> and as such has the
    same security issues as <function>eval</function>. Additionally it has bad performance
    and memory usage characteristics.
   </para>
   <para>
    If you are using PHP 5.3.0 or newer a native
    <link linkend="functions.anonymous">anonymous function</link> should be used instead.
   </para>
  </caution>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Usually these parameters will be passed as single quote delimited strings.
   The reason for using single quoted strings, is to protect the variable
   names from parsing, otherwise, if you use double quotes there will be a
   need to escape the variable names, e.g. <literal>\$avar</literal>.
   <variablelist>
    <varlistentry>
     <term><parameter>args</parameter></term>
     <listitem>
      <para>
       The function arguments.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>code</parameter></term>
     <listitem>
      <para>
       The function code.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a unique function name as a string, or &false; on error.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Creating an anonymous function with <function>create_function</function>
    </title>
    <para>
     You can use this function, to (for example) create a function from
     information gathered at run time:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$newfunc = create_function('$a,$b', 'return "ln($a) + ln($b) = " . log($a * $b);');
echo "New anonymous function: $newfunc\n";
echo $newfunc(2, M_E) . "\n";
// outputs
// New anonymous function: lambda_1
// ln(2) + ln(2.718281828459) = 1.6931471805599
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Or, perhaps to have general handler function that can apply a set
   of operations to a list of parameters:
  </para>
  <para>
   <example>
    <title>
     Making a general processing function with
     <function>create_function</function>
    </title>
    <programlisting role="php">
<![CDATA[
<?php
function process($var1, $var2, $farr)
{
    foreach ($farr as $f) {
        echo $f($var1, $var2) . "\n";
    }
}

// create a bunch of math functions
$f1 = 'if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}';
$f2 = "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);";
$f3 = 'if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; }';
$farr = array(
    create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'),
    create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'),
    create_function('$a,$b', $f1),
    create_function('$a,$b', $f2),
    create_function('$a,$b', $f3)
    );

echo "\nUsing the first array of anonymous functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);

// now make a bunch of string processing functions
$garr = array(
    create_function('$b,$a', 'if (strncmp($a, $b, 3) == 0) return "** \"$a\" '.
    'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'),
    create_function('$a,$b', '; return "CRCs: " . crc32($a) . ", ".crc32($b);'),
    create_function('$a,$b', '; return "similar(a,b) = " . similar_text($a, $b, &$p) . "($p%)";')
    );
echo "\nUsing the second array of anonymous functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Using the first array of anonymous functions
parameters: 2.3445, M_PI
some trig: -1.6291725057799
a hypotenuse: 3.9199852871011
b*a^2 = 4.8103313314525
min(b^2+a, a^2,b) = 8.6382729035898
ln(a)/b = 0.27122299212594

Using the second array of anonymous functions
** "Twas the night" and "Twas brilling and the slithy toves"
** Look the same to me! (looking at the first 3 chars)
CRCs: -725381282, 342550513
similar(a,b) = 11(45.833333333333%)
]]>
    </screen>
   </example>
  </para>
  <para>
   But perhaps the most common use for of lambda-style (anonymous) functions
   is to create callback functions, for example when using
   <function>array_walk</function> or <function>usort</function>
  </para>
  <para>
   <example>
    <title>Using anonymous functions as callback functions</title>
    <programlisting role="php">
<![CDATA[
<?php
$av = array("the ", "a ", "that ", "this ");
array_walk($av, create_function('&$v,$k', '$v = $v . "mango";'));
print_r($av);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
  [0] => the mango
  [1] => a mango
  [2] => that mango
  [3] => this mango
)
]]>
    </screen>
    <para>
     an array of strings ordered from shorter to longer
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$sv = array("small", "larger", "a big string", "it is a string thing");
print_r($sv);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
  [0] => small
  [1] => larger
  [2] => a big string
  [3] => it is a string thing
)
]]>
    </screen>
    <para>
     sort it from longer to shorter
    </para>
    <programlisting role="php">
<![CDATA[
<?php

usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
print_r($sv);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
  [0] => it is a string thing
  [1] => a big string
  [2] => larger
  [3] => small
)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="functions.anonymous">Anonymous functions</link></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->