documentation and examples of use of create_function() to generate

anonymous (lambda-style) functions


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@30672 c90b9560-bf6c-de11-be94-00142212c4b1

functions/misc.xml

@@ -9,6 +9,152 @@
    </para>
   </partintro>
 
+  <refentry id="function.create-function">
+   <refnamediv>
+    <refname>create_function</refname>
+    <refpurpose>Create an anonymous (lambda-style) function</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <funcsynopsis>
+     <funcprototype>
+      <funcdef>string <function>create_function</function></funcdef>
+      <paramdef>string <parameter>args</parameter></paramdef>
+      <paramdef>string <parameter>code</parameter></paramdef>
+     </funcprototype>
+    </funcsynopsis>
+    <para>
+	 Creates an anonymous function from the parameters passed, and
+	 returns a unique name for it. Usually the
+	 <parameter>args</parameter> will be passed as a single quote
+	 delimited string, and this is also recommended for the
+	 <parameter>code</parameter>. 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>.
+	</para>
+	<para>
+	 You can use this function, to (for example) create a function
+	 from information gathered at run time:
+	 <example>
+	  <title>
+	   Creating an anonymous function with <function>create_function</function>
+	  </title>
+	  <programlisting role="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>
+	 Or, perhaps to have general handler function that can apply a set
+	 of operations to a list of parameters:
+	 <example>
+	  <title>
+	   Making a general processing function with
+	   <function>create_function</function>
+	  </title>
+	  <programlisting role="php">
+function process($var1, $var2, $farr) {
+	for ($f=0; $f &lt; count($farr); $f++)
+		echo $farr[$f]($var1,$var2)."\n";
+}
+
+// create a bunch of math functions
+$f1 = 'if ($a &gt;=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 &gt; 0 &amp;&amp; $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>
+	 and when you run the code above, the output will be:
+	 <informalexample>
+	  <programlisting>
+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 , 1908338681
+similar(a,b) = 11(45.833333333333%)
+	  </programlisting>
+	 </informalexample>
+	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>
+	<example>
+	 <title>Using anonymous functions as callback functions</title>
+	 <programlisting role="php">
+$av = array("the ","a ","that ","this ");
+array_walk($av, create_function('&$v,$k','$v = $v."mango";'));
+print_r($av);  // for PHP3 use var_dump()
+// outputs:
+// Array
+// (
+//     [0] =&gt; the mango
+//     [1] =&gt; a mango
+//     [2] =&gt; that mango
+//     [3] =&gt; this mango
+// )
+
+// an array of strings ordered from shorter to longer
+$sv = array("small","larger","a big string","it is a string thing");
+print_r($sv);
+// outputs:
+// Array
+// (
+//     [0] =&gt; small
+//     [1] =&gt; larger
+//     [2] =&gt; a big string
+//     [3] =&gt; it is a string thing
+// )
+
+// sort it from longer to shorter
+usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
+print_r($sv);
+// outputs:
+// Array
+// (
+//     [0] =&gt; it is a string thing
+//     [1] =&gt; a big string
+//     [2] =&gt; larger
+//     [3] =&gt; small
+// )
+	 </programlisting>
+	</example>
+    </para>
+   </refsect1>
+  </refentry>
+
   <refentry id="function.connection-aborted">
    <refnamediv>
     <refname>connection_aborted</refname>